Connect GitHub Issues: step-by-step guide
Opens one GitHub issue per failing test, comments on it when the test fails again, and closes it when the test passes clean. GitHub takes no file uploads, so the issue names the evidence folder instead of attaching the screenshot. This guide takes you from nothing to a verified connection, and lists the errors you can meet with their cause and fix.
Last updated:
Keep your credentials private. Never paste a token, key, password or webhook URL into a chat. Type it only in Studio → Settings → Integrations, where it is saved in your workspace's .env file and shown as dots. The same goes for an AI assistant: it can walk you through this guide, but it never needs your token.
What you need
- A GitHub account that can open issues in the repository (a collaborator, or the owner).
- A repository with Issues switched on (repository Settings → Features → Issues).
- A fine-grained personal access token with Issues → Read and write on that repository, or a classic token with the repo scope.
Get the credentials
- Open https://github.com/settings/personal-access-tokens/new (a fine-grained token).
- Name it, set an expiry, and under Repository access choose Only select repositories, then pick the repository that will receive the issues.
- Under Permissions → Repository permissions set Issues to Read and write. Nothing else is needed.
- Generate the token and copy it now. GitHub shows it once. Do not paste it anywhere except the Studio (next step).
Connect it in the Studio
- In the Studio, open Settings → Integrations → Connect GitHub Issues.
- When it asks, enter the token and press Save & check. The Studio shows who the token belongs to and how many repositories it reaches.
- Pick the repository in "Issues go to". The list only offers repositories the token can reach and that have Issues on.
- Turn on
GITHUB_ISSUES_ENABLED.
Check that it works
- Check connection shows "signed in as <you>" and "<owner/repo> takes issues". The check only reads; it never opens an issue.
- Open Settings → Integrations → Tickets and press Create test ticket on the GitHub destination. It opens one issue labelled nexus-test.
- Open it on GitHub, confirm the label, and close or delete it when you are done.
Common errors
| What you see | Cause | Fix |
|---|---|---|
| "GitHub refused the token (401)" | The token is wrong, expired, revoked or copied incompletely. | Create a new token with Issues → Read and write and save it again. |
| HTTP 403 | The token lacks the Issues permission, the repository was not selected for it, or the rate limit is spent. | Edit the token: set Issues to Read and write and select the repository. If it is the rate limit, wait a few minutes. |
| HTTP 404 | The repository does not exist, was renamed, or the token cannot see it (private repositories must be selected on a fine-grained token). | Pick the repository from the list, or add it to the token's repository access. |
| HTTP 422 | GitHub rejected a field of the issue, most often an assignee who is not a collaborator, or a title or label GitHub refuses. | Clear the assignee in Settings → Integrations → Tickets, or add that person as a collaborator. |
| "<repo> has Issues switched off" | The repository has the Issues feature disabled. | Turn on Settings → Features → Issues in the repository, or choose another one. |
| "could not reach GitHub (…)" or "did not answer in time" | This PC cannot reach api.github.com: a VPN or proxy, or no network. | Open github.com in a browser on the same PC, then retry the check. |
| Everything checks out, but no issue appears | GITHUB_ISSUES_ENABLED is false; or the verdict was FLAKY or an environment verdict; or it was a sandbox run; or the test already has an open issue (a repeat failure comments instead). | Turn on GITHUB_ISSUES_ENABLED and use Create test ticket to prove the connection. |
Settings keys
| Key | What it does | Valid value | How to check it |
|---|---|---|---|
GITHUB_ISSUES_ENABLED | Create GitHub issues for failures | true or false | Turn on after Check connection passes, then run Create test ticket. |
GITHUB_ISSUES_TOKEN | GitHub access token (secret, saved only on this computer) | One line, no quotes, no spaces | Check connection: "refused the token" means it is wrong, expired or revoked. |
GITHUB_ISSUES_REPO | GitHub repository for issues | owner/repo, like acme/web | Pick it from the list; the Studio only saves a repository the token reaches and that has Issues on. |
More: all integrations, the Settings guide, troubleshooting. Other guides: Jira Cloud, Azure Boards, Slack, Microsoft Teams, Telegram.
Still stuck? Write to [email protected] with the exact error line the Studio shows. Do not include a token.