GitHub

Connecting GitHub gives nima your repositories and the pull requests in them. nima indexes the code so specs are grounded in it, links each pull request to the ticket it belongs to, moves that ticket as review progresses, turns review comments into signals, and marks the spec shipped when the last linked pull request merges.

Connect GitHub to nima

To connect GitHub, an owner or admin installs nima's GitHub app on the account that owns the repositories, from Integrations in the admin panel. The caller needs the permission to manage integrations.

Three rules apply:

• One installation per workspace. Connecting again replaces the installation. An installation already claimed by another workspace is refused with a conflict error.
• Repositories follow the installation. Adding a repository on GitHub syncs and indexes it. Removing one deletes nima's record of it, including its pull request records, their links to cards and its drift-check history. Its code index is kept, and code search keeps covering it, until you disconnect GitHub. Repository access changes made on GitHub are picked up without reconnecting.
• Board linking is automatic only in one case. nima links a repository to a board for you only when exactly one repository and exactly one board are unlinked. Otherwise nothing is linked, and pull requests from that repository are recorded but move no ticket until you link a board with PATCH /v1/github/repositories/:id/board and a body of { "kanbanBoardId": "<board id>" } (or null to unlink). A board can serve only one repository; a second link returns 409.

Read the connection with GET /v1/github/app/status, which returns installed, accountLogin, repoCount and settingsUrl (the GitHub page where you manage repository access). GET /v1/github/repositories lists the repositories, up to 1,000.

GitHub permissions

GitHub's install screen shows the exact permissions nima's app requests, and they cover only the repositories you select. The app's permission set lives on GitHub, not in nima, so read the install screen for the authoritative list.

The reader app is the one you install to connect. It reads code, pull requests and comments. The only thing it writes is the drift-check comment on a pull request, and posting that comment needs pull_requests write. The comment is titled "PRD Drift Check" and carries a table with a verdict per spec section (aligned, drifted or not_addressed). It is posted, and updated in place, only for pull requests matched to a spec that has been enrolled for drift checks, and only while the app is not suspended. Its link back to the spec lands on Integrations, because the admin panel has no spec page.

Anything that publishes commits or comments for agent operations goes through a separate app. See the optional GitHub writer app.

What arrives from GitHub

nima subscribes to these GitHub events and does the following with each.

Issues events, releases, labels and commits are not handled.

Review and issue comments become signals

Each pull request review comment and each issue or pull request comment becomes one signal with source github and origin external. The signal keeps the repository (owner/repo), the pull request or issue number and title, the author login, the file path for review comments, and a link back to the comment. Signals then follow the normal path into beacons. nima applies no filter for comments written by bots or by nima itself.

Pull requests link to spec tickets

A pull request links to the ticket created when a spec was promoted to a board card, and moves that card as review progresses. The whole loop from spec to merge is on Delivery.

nima looks for a ticket key such as ACME-42 in the pull request title and description, and in the branch name after a slash (feat/ACME-42-login). When none of them names a ticket, an AI match against the board's non-archived cards is the fallback, accepted at a confidence of 0.7 or higher. Linking needs three things: the webhook delivery, a repository linked to a board, and a card with a ticket number on that board (a promoted spec's card, or one synced from Jira). Without a board, or without a matching card, the pull request is recorded and nothing moves.

By default these events move the card:

Approvals, new pushes, drafts and plain closes move nothing by default. A .nima.yml at the repository root can change the transitions, the enabled events and the AI matching settings (ai_matching.enabled, ai_matching.min_confidence), and board (a ticket prefix that picks a board when the repository has none linked). nima reads that file only when a push touches it, and invalid YAML keeps the previous configuration. The branch_pattern key is accepted but does nothing; the branch matching is fixed.

A spec is marked shipped when no open pull request remains on its card, so the last merge ships it, not the first.

Merged pull requests feed the knowledge graph

Each merged pull request is queued for extraction into the knowledge graph, so decisions in pull request descriptions become searchable with ask_knowledge_graph. Only merged pull requests are extracted, and extraction runs for repositories nima has indexed.

Default-branch pushes re-index the code

A push to a repository's default branch triggers an incremental index of that repository, and the result is what code search reads. Pushes to other branches, tags and branch deletions are skipped. If indexing fails twice in a row, the next push runs a full index. After three consecutive failures, push-driven indexing stops until you re-index by hand.

To re-index by hand, call POST /v1/code-intel/repositories/:id/reindex with a signed-in owner or admin session. :id is the repository's id from GET /v1/code-intel/repositories, not the id from GET /v1/github/repositories. The route is declared under the code_intelligence plan feature. Each repository can be re-indexed this way once every 24 hours; a second call inside that window returns a rate-limit error with the time you can retry.

CI results wake parked agent operations

When an agent operation waits for CI, a completed check_suite or workflow_run on the operation's branch resumes it, provided the head commit matches the one the operation last published. nima's GitHub app subscribes to both events; you do not configure anything. See Agent operations.

GitHub limits

• No replay for signals or tickets. Comments written before you connected do not become signals, and earlier pull requests are not linked to cards or added to the knowledge graph. Indexing does read up to two years of pull request history (titles, descriptions, changed files and review comments) into the code history that code search uses.
• Comments only, for signals. Pull request and issue descriptions, pushes, labels, releases and issue events do not become signals.
• One board per repository, and one repository per board.
• Manual re-index: once per repository every 24 hours. It needs a signed-in owner or admin session.
• Repository lists stop at 1,000. GET /v1/github/repositories returns at most 1,000 repositories.
• Pausing does not stop anything. The enable and disable switch on the integration is a label. Pull requests and comments keep arriving while it reads Paused.

The optional GitHub writer app for publishing

The GitHub writer app is a second, separately installed app that lets nima's hosted virtual machines publish work to your repositories. The reader app you connected above never publishes commits or replies. Its only write is the drift-check comment.

Installing the writer does not turn publishing on. Publishing stays off until an owner or admin enables it, and it is independent of the hosted compute setting.

The Slack commands need a linked workspace owner or admin. Anything that changes state posts a Confirm button and also accepts confirm <nonce> within 5 minutes. The MCP tools, and the REST routes when called with a key, need an API key with the integrations:write scope, which an admin mints in Slack with /nima mcp-key integrations (valid 30 days). The caller must still be a workspace owner or admin. See MCP operation tools and Writers.

What the writer can do:

• Publish work from hosted operations. Implementing a spec opens a new draft pull request, and fixing CI pushes commits to the existing one; both need contents and pull_requests write. Reproduce-issue operations can post a comment, or open a draft pull request after the proposed fix is approved; check operations can post a comment, which needs only pull_requests write. Report-only operations do not need the writer. Hosted operations are enabled by the nima team on request; see Hosted VMs.
• Comment on pull requests. Replying on GitHub is an outbound action. It needs the writer connected with pull_requests write, publishing turned on, and outbound actions turned on for the workspace, and each reply follows the outbound actions approval rules. Replies work on pull requests only. A reply aimed at a plain issue is refused with a validation error, because the writer app does not hold issues write.

The writer mints a token for one repository at a time, at the moment of publishing. A publish that cannot proceed is refused with a reason such as github_write_disabled, writer_not_connected, writer_repository_unavailable or writer_permissions_missing; it is never downgraded to a report. See Hosted VMs.

Disconnect GitHub

To disconnect GitHub, call DELETE /v1/integrations/github (or DELETE /v1/github/app/uninstall), or use Disconnect on the GitHub card in Integrations. nima deletes its installation row and the repositories it tracked.

That does not uninstall the app on GitHub. Remove it there too, from the Manage repositories link on the card, or GitHub keeps the installation. If you uninstall on GitHub first, GitHub's installation deleted event makes nima drop the installation for you.

Disconnecting deletes no signals, specs or cards. It does delete everything nima kept per repository: the pull request records, their links to cards, drift-check history, and the code index for those repositories, so code search no longer covers them. Reconnecting re-indexes the code, but earlier pull requests are not linked to cards again. The writer app is separate: disconnect it with the writer commands above, and uninstall it on GitHub as well.