GitHub Integration — QA Note Docs

What is GitHub Integration?

QA Note's GitHub integration supports bidirectional synchronization. Issues created in QA Note are automatically created on GitHub, and status changes on GitHub are reflected back in QA Note. Comments and labels are also synced in real-time on both sides.

Setup

1. Connect GitHub Account

Go to Project Settings → Integrations tab and click the Connect GitHub button. Your account will be connected through the GitHub OAuth authentication process.

The connection requests repo (issue creation) and project (GitHub Projects access) permissions.

2. Repository Settings

After connecting, enter the GitHub repository to sync issues with in owner/repo format. Once you set the repository, a Webhook is automatically registered, enabling bidirectional sync.

3. Auto-Sync Settings

When Auto-Sync is enabled (default), a GitHub issue is automatically created whenever you submit a new issue in QA Note. You can disable this as needed.

Sync Scope

QA Note → GitHub

Item	Sync Details
Issue Creation	GitHub issue is automatically created when a QA Note issue is submitted. Includes screenshots, environment info, console errors, network errors, user action timeline, and session replay link.
Status Changes	When status changes in QA Note, the GitHub issue's open/closed state and `status:*` labels are updated.
Comments	Comments written in QA Note are synced to GitHub. Edits and deletions are also reflected.
Labels	When labels change in QA Note, the GitHub issue labels are updated.

GitHub → QA Note

Item	Sync Details
Status Changes	When an issue is closed/reopened or `status:*` labels are changed on GitHub, the QA Note status is updated.
Comments	Comments written on GitHub are synced to QA Note. Edits and deletions are also reflected.
Labels	When labels are added/removed on GitHub, they are reflected in QA Note. New labels are automatically created.

To prevent echo (infinite loops), duplicate syncs within 5 seconds are automatically ignored.

Status Labels

QA Note issue statuses are represented as labels with the status: prefix on GitHub.

QA Note Status	GitHub Label
open	`status:open`
in_progress	`status:in-progress`
resolved	`status:resolved`
closed	`status:closed`

If you define custom statuses (kanban columns) in your project, they are synced using the same pattern.

GitHub Projects v2

If you're using GitHub Projects v2, you can automatically add QA Note issues to your project board.

Setup

Find the GitHub Projects section in Project Settings → Integrations tab.
Select the project you want to use from the connected GitHub account's project list.
Select the Status field (Single Select type field).
Set up the mapping between QA Note statuses and GitHub Projects options.

After setup, when you create an issue in QA Note, it's automatically added to the GitHub Projects board, and status changes update the project board status as well.

Import GitHub Issues

You can bulk import existing GitHub issues into QA Note.

Click the Import Issues button in Project Settings → Integrations tab.
Review the list of issues to import in the preview.
Configure mapping for status, priority, assignee, and milestone.
Click Start Import and issues and comments will be imported sequentially.

The process respects GitHub API rate limits, ensuring stable imports even for large numbers of issues.

Auto-PR via AI Fix

When GitHub integration is enabled, clicking AI Fix · Plan + Implement on a QA Note issue pushes the fix that Claude Code generates straight into the linked GitHub repository as a pull request.

Prerequisites

The QA Note GitHub App must be installed on the target repository.
The installation needs permission to create branches outside the default (main · master).
If Vercel is also connected, opening the auto PR triggers a Preview deploy in the same step. See Vercel integration.

PR Creation Flow

Step	Actor	Result
① Plan	Claude Code	Drafts the fix plan
② Branch	QA Note GitHub App	Creates `qanote/fix/{issue}-{short}` branch
③ Commit	Claude Code	Commits and pushes the change
④ PR	QA Note GitHub App	Opens PR #N · links it back to the issue

The PR body includes the QA Note issue permalink automatically. For the full pipeline see the AI Fix · auto PR guide.

Permission Scope

The QA Note GitHub App requests only the following permissions:

Contents: Read & Write (branch · commit creation)
Pull Requests: Read & Write (open · update PRs)
Issues: Read (issue sync · status label mirror)
Metadata: Read (basic repository info)

Repository selection is configured during GitHub App installation. To add new repositories, update the repository selection in your GitHub App settings.

Retry GitHub Issues

If a GitHub issue creation fails, you can retry using the Retry button on the issue detail page.

What is GitHub Integration?

Setup

1. Connect GitHub Account

Go to Project Settings → Integrations tab and click the Connect GitHub button. Your account will be connected through the GitHub OAuth authentication process.

The connection requests repo (issue creation) and project (GitHub Projects access) permissions.

2. Repository Settings

After connecting, enter the GitHub repository to sync issues with in owner/repo format. Once you set the repository, a Webhook is automatically registered, enabling bidirectional sync.

3. Auto-Sync Settings

When Auto-Sync is enabled (default), a GitHub issue is automatically created whenever you submit a new issue in QA Note. You can disable this as needed.

Sync Scope

QA Note → GitHub

Item	Sync Details
Issue Creation	GitHub issue is automatically created when a QA Note issue is submitted. Includes screenshots, environment info, console errors, network errors, user action timeline, and session replay link.
Status Changes	When status changes in QA Note, the GitHub issue's open/closed state and `status:*` labels are updated.
Comments	Comments written in QA Note are synced to GitHub. Edits and deletions are also reflected.
Labels	When labels change in QA Note, the GitHub issue labels are updated.

GitHub → QA Note

Item	Sync Details
Status Changes	When an issue is closed/reopened or `status:*` labels are changed on GitHub, the QA Note status is updated.
Comments	Comments written on GitHub are synced to QA Note. Edits and deletions are also reflected.
Labels	When labels are added/removed on GitHub, they are reflected in QA Note. New labels are automatically created.

To prevent echo (infinite loops), duplicate syncs within 5 seconds are automatically ignored.

Status Labels

QA Note issue statuses are represented as labels with the status: prefix on GitHub.

QA Note Status	GitHub Label
open	`status:open`
in_progress	`status:in-progress`
resolved	`status:resolved`
closed	`status:closed`

If you define custom statuses (kanban columns) in your project, they are synced using the same pattern.

GitHub Projects v2

If you're using GitHub Projects v2, you can automatically add QA Note issues to your project board.

Setup

Find the GitHub Projects section in Project Settings → Integrations tab.
Select the project you want to use from the connected GitHub account's project list.
Select the Status field (Single Select type field).
Set up the mapping between QA Note statuses and GitHub Projects options.

After setup, when you create an issue in QA Note, it's automatically added to the GitHub Projects board, and status changes update the project board status as well.

Import GitHub Issues

You can bulk import existing GitHub issues into QA Note.

Click the Import Issues button in Project Settings → Integrations tab.
Review the list of issues to import in the preview.
Configure mapping for status, priority, assignee, and milestone.
Click Start Import and issues and comments will be imported sequentially.

The process respects GitHub API rate limits, ensuring stable imports even for large numbers of issues.

Auto-PR via AI Fix

When GitHub integration is enabled, clicking AI Fix · Plan + Implement on a QA Note issue pushes the fix that Claude Code generates straight into the linked GitHub repository as a pull request.

Prerequisites

The QA Note GitHub App must be installed on the target repository.
The installation needs permission to create branches outside the default (main · master).
If Vercel is also connected, opening the auto PR triggers a Preview deploy in the same step. See Vercel integration.

PR Creation Flow

Step	Actor	Result
① Plan	Claude Code	Drafts the fix plan
② Branch	QA Note GitHub App	Creates `qanote/fix/{issue}-{short}` branch
③ Commit	Claude Code	Commits and pushes the change
④ PR	QA Note GitHub App	Opens PR #N · links it back to the issue

The PR body includes the QA Note issue permalink automatically. For the full pipeline see the AI Fix · auto PR guide.

Permission Scope

The QA Note GitHub App requests only the following permissions:

Contents: Read & Write (branch · commit creation)
Pull Requests: Read & Write (open · update PRs)
Issues: Read (issue sync · status label mirror)
Metadata: Read (basic repository info)

Repository selection is configured during GitHub App installation. To add new repositories, update the repository selection in your GitHub App settings.

Retry GitHub Issues

If a GitHub issue creation fails, you can retry using the Retry button on the issue detail page.