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	Closing a GitHub issue can move an active QA Note record to `fix_submitted`. Active `status:*` labels are synced. Reopening does not bypass QA Note's human verification gate.
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`
blocked	`status:blocked`
fix_submitted	`status:fix-submitted`
verified	`status:verified`
closed	`status:closed`

The six statuses are fixed. verified can only be selected by a human in QA Note, and closed is produced when a report is published.

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.

Commit & Deploy Records (write-back)

When GitHub integration is enabled, the push webhook detects issue keys (e.g. QANOTE-42) in commit messages, transitions the issue to fix submitted, and links the commit to the issue. When deployment events arrive, QA Note correlates them with fix commits and marks the issue "ready to verify."

Because this record path piggybacks on commits developers already make, the record survives without any agent or dashboard. See Commit Keys for details.

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	Closing a GitHub issue can move an active QA Note record to `fix_submitted`. Active `status:*` labels are synced. Reopening does not bypass QA Note's human verification gate.
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`
blocked	`status:blocked`
fix_submitted	`status:fix-submitted`
verified	`status:verified`
closed	`status:closed`

The six statuses are fixed. verified can only be selected by a human in QA Note, and closed is produced when a report is published.

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.

Commit & Deploy Records (write-back)

Because this record path piggybacks on commits developers already make, the record survives without any agent or dashboard. See Commit Keys for details.

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.