GitHub Integration
Bidirectionally sync issues, statuses, and comments with GitHub
Table of Contents
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.