Skip to main content

​
Summary

This page explains the GitHub integration at a glance and the two integration directions:
  • Outbound (Nota → GitHub): Nota uses a GitHub access token to list issues and file new issues from workflow runs.
  • Inbound (GitHub → Nota): GitHub sends webhook events — new issues trigger coverage discovery, @nota mentions in issue and pull-request comments get an in-thread reply, and pull-request content is ingested as context.
Includes the required token permissions, a setup checklist, testing steps, and common troubleshooting scenarios.

​
🐙 GitHub (team feature)

Connecting GitHub has two directions:
  • Outbound (Nota → GitHub) — Nota lists issues and files new ones. Needs an access token.
  • Inbound (GitHub → Nota) — new issues kick off coverage discovery, @nota mentions get an in-thread reply, and pull-request content is ingested. Needs a webhook, and (for mentions) a dedicated Nota account.
Set up outbound first. Inbound routing depends on a value Nota resolves when you save the outbound token — see Outbound Step 2.
For the full experience — where replies post as Nota and teammates can @-mention it — create the dedicated Nota account in the Inbound section first, then generate the outbound token from that account. GitHub attributes every API action to whichever account owns the token.

​
Outbound — let Nota act on your repositories

From chat, GitHub is create-only. Nota can list issues and create new ones. There is no chat tool to comment on, assign, close, label, or otherwise update an existing GitHub issue or pull request. Ask for one of those and Nota hands off explicitly rather than quietly filing a new issue instead. If you need full write access from chat, use Linear, Jira, or GitLab.(Inbound @nota mention replies do post a comment — that’s the reply path Nota owns, not a chat tool you can point at an arbitrary thread.)

​
Step 1 — Create the GitHub access token

  1. On github.com, click your profile photo (top-right) → Settings.
  2. In the left sidebar, scroll to Developer settings → Personal access tokens → Fine-grained tokens.
  3. Click Generate new token, name it, and set an expiry.
  4. Under Repository access, pick the repositories Nota should work with (or All repositories).
  5. Under Permissions → Repository permissions, grant:
  6. Click Generate token, then copy and save it — GitHub shows it only once. This is your GitHub Access Token.
A classic token with the repo scope also authenticates, but repo grants far more than Nota needs (full read/write on code, not just issues). Prefer a fine-grained token scoped to the repositories you actually want covered.

​
Step 2 — Pick the default repository

The field is labelled optional, but inbound webhooks need it.On save, Nota calls GET /repos/{owner}/{repo} with your token and stores the repository’s canonical GitHub Owner login. That owner is what routes inbound webhook deliveries to your team.If no default repository is set — or the token can’t read it — the owner never resolves and every GitHub webhook is rejected as an unregistered workspace (see Troubleshooting). Outbound still works fine without it; chat supplies a repository per request.
Enter it as owner/repo exactly as it appears in the GitHub URL:
  • ✅ my-org/my-repo
  • ❌ https://github.com/my-org/my-repo (no host)
  • ❌ /my-org/my-repo (no leading slash)
  • ❌ my-repo (owner is required)
Casing doesn’t matter — Nota stores GitHub’s canonical casing from the API response, so a mixed-case entry can’t desync from inbound deliveries. The token must be able to read that repository; the same API call is what validates it.

​
Step 3 — Configure Nota

Go to app.trynota.ai/integrations and click GitHub Settings. Fill in: Click Update Settings — Nota uses it immediately, no redeploy needed. On save Nota also resolves and stores your GitHub Owner automatically; that’s what routes inbound webhooks to your team later. Leave GitHub Webhook Secret and Nota Bot Username blank for now — they’re covered in the Inbound section.
You’re done with outbound. In Nota chat, say “list my open GitHub issues” — you should see your issues. Then try “file a GitHub issue for the last failing run” — it should create one and hand you the URL.

​
Inbound — issue events, @nota mentions & PR content

​
Step 1 — Create a dedicated Nota account

Only needed for @nota mention replies. Skip it if you just want new-issue discovery and pull-request ingestion.
  1. Create (or reuse) an email for the bot, e.g. nota@<your-domain>.
  2. Sign up a GitHub account with it and note its username — the exact text after @ when you mention it (if the @-menu shows @nota-bot, the username is nota-bot).
  3. Invite that account to your organization / repositories with at least write access so it can post comments.
Replies post using the outbound access token, so they’re attributed to whichever account owns that token. For replies to appear as Nota, generate the fine-grained token from the bot account (Outbound Step 1) rather than from your own.

​
Step 2 — Generate a webhook secret

Generate a high-entropy secret and save it — you’ll paste the same value into GitHub (Step 3) and Nota (Step 4):
GitHub signs every delivery with HMAC-SHA256 over this secret and sends the digest in the X-Hub-Signature-256 header; Nota verifies against the copy you store. On the hosted app it’s required — without it, deliveries are rejected.

​
Step 3 — Create the webhook in GitHub

Go to your repository → Settings → Webhooks → Add webhook (or Organization settings → Webhooks to cover every repo at once), then:
Content type must be application/json. The application/x-www-form-urlencoded option wraps the whole event inside a payload= form field, which Nota’s parser rejects — every delivery fails.
Under Which events would you like to trigger this webhook?, choose Let me select individual events and enable: Click Add webhook.
Unlike Linear — which generates a signing secret for you at webhook creation — you supply this secret, the same way GitLab’s Secret token works. GitHub differs from GitLab in one respect: it signs the request body (HMAC-SHA256) rather than echoing the raw secret back in a header.

​
Step 4 — Configure Nota

Back in app.trynota.ai/integrations → GitHub Settings, fill in: Click Update Settings.

​
Step 5 — Test it

Mention Nota from a different account. As yourself (not the Nota account), open an issue or pull request, add a comment, and type the bot’s username — @nota-bot what does this issue cover?. Post it — Nota replies in-thread within a few seconds.The mention is matched case-insensitively (@Nota-Bot works), and the @ must be followed by the exact username — a longer handle like @nota-bot-staging is not treated as a mention of nota-bot.
Open a new issue. Nota picks it up and starts discovering test coverage for the surface the issue describes.
Mention the bot from a human account, not as the bot. The loop guard drops any comment whose author is the Nota account, so if you configure your own username and mention yourself, Nota stays silent by design (it must never reply to itself). Use the dedicated bot account’s username and mention it from your normal account.
Comment edits and deletions are ignored — only newly-created comments trigger a reply. Post a fresh comment rather than editing an existing one.
GitHub logs every delivery under Settings → Webhooks → your webhook → Recent Deliveries. Expand one to see the exact request and Nota’s response — a 202 means Nota accepted and queued the event.

​
What each inbound event does

Pull-request events are ingest-only. Nota stores the PR’s metadata and diff so later questions and runs have that context, but a pull request never starts a workflow run on its own. Metadata-only PR activity — labels, assignees, review requests, milestones — is ignored entirely.

​
Troubleshooting

Quick isolation: GitHub’s Recent Deliveries tab shows the exact request and Nota’s response for every event — a 403 points at the secret, a 200 unregistered_platform_workspace points at the Default Repository. Treat the access token and webhook secret like passwords, and rotate them if you suspect either has leaked.