Jira

Connecting Jira keeps one Jira site and one nima kanban board in sync both ways. Jira issues arrive as board cards, a status change in Jira moves the card, and when a pull request moves the card, the issue moves in Jira too. With outbound dispatch on, nima can also react to ticket events and propose comments on tickets.

Connect Jira

Connecting Jira takes a workspace owner or admin (the MANAGE_INTEGRATIONS permission) and one Atlassian consent screen. In the web app, open Integrations, open Jira, click Connect Jira and authorize nima at Atlassian. From a signed-in session, POST /v1/integrations/jira/connect returns { "url": ... }, the Atlassian consent URL to send the browser to. API keys and OAuth tokens cannot call the Jira connection routes.

nima uses the first Jira site your Atlassian account can reach. There is no site chooser. If the account reaches no site, the connect fails with No accessible Jira sites for this account.

nima syncs onto one kanban board. On the first connect, if the workspace has a board, nima selects the newest one automatically. To change it, pick another board in the Synced board selector on the Jira row in Integrations, or call PATCH /v1/jira/app/board with { "boardId": "<uuid>" } from a signed-in session. If the workspace has no board, create one first. From a signed-in session, call POST /kanban/boards with { "title": "Engineering", "ticketPrefix": "ENG" } (the prefix is 1 to 3 uppercase letters); the new board gets the default columns. Then pick it in Synced board. Nothing syncs until a board is selected. Changing the board clears the status mapping, proposes a new one and re-runs the sync. The API call returns 404 when Jira is not connected or the board does not belong to the workspace, and 400 when boardId is missing.

GET /v1/jira/app/status returns installed, siteName, siteUrl, boardId, connectionInvalid and the current statusMapping.

Permissions nima asks Jira for

Atlassian lists these as granular scopes.

nima reads and transitions issues as the person who authorized it, so it sees what they see. The comment scopes are not part of this consent screen. Comments need a service-account writer; see Jira writer modes below.

Jira issues become board cards

Each synced Jira issue becomes a kanban card, not a signal. Jira never creates signals in nima. The card is titled with the issue summary, labelled jira, numbered with the workspace's next ticket number, and stores the issue key, status and URL.

• Status to column. nima maps each Jira status to a column of the synced board. A model proposes the mapping from your status names and column titles, with a deterministic heuristic as fallback, and the result is limited to real column titles. There is no route or control to edit the mapping. Changing the board re-proposes it.
• Backfill on connect. nima imports issues updated in the last 30 days, up to 200. Issues older than that arrive when they next change.
• Ongoing changes arrive through a Jira webhook that watches the first 50 project keys on the site. Issue created and updated events upsert the card and move it to the mapped column.
• Deleted issues. When an issue is deleted in Jira, nima archives its card and drops the link.
• No board, no cards. If no board is selected or the board has no columns, the sync skips issues and logs a warning.

Card moves write status back to Jira

When a linked card changes column, nima transitions its Jira issue. Cards change column in two ways: a pull request event moves the card (see GitHub), or a signed-in session calls PATCH /kanban/cards/:id/move with { "columnId": "<uuid>", "position": 0 }. API keys and MCP cannot move cards, and the admin panel has no board view. nima reverse-maps the destination column to a Jira status, reads the issue's live transitions and applies the one that leads to that status. If no name matches, it falls back to the status category implied by the column title: a title with done, complete, shipped or closed means Done, one with progress, doing or review means In Progress, anything else means To Do.

If Jira offers no matching transition, nothing changes in Jira. nima does not create Jira issues from cards or specs and does not edit issue fields. A merged pull request that moves a card to the done column transitions its Jira issue the same way, because PR events move cards through the same path. See GitHub for how PRs link to cards.

Jira webhook expiry and resync

Jira's dynamic webhooks expire 30 days after they are created or refreshed. nima refreshes a webhook once fewer than 7 days remain, whenever it sees activity: an incoming Jira webhook, or a status read (opening the Jira row in Integrations, or GET /v1/jira/app/status). In a workspace with outbound dispatch on, an hourly sweep also refreshes expiring webhooks, registers a new one when none is live, and re-registers one whose event set has drifted. In a workspace without outbound dispatch, a webhook stays alive only if a Jira event arrives or someone reads the Jira status during its last 7 days. With no activity in that window it expires, and syncing stops without warning, possibly after only a week of quiet.

To recover, press Sync now on the Jira row in Integrations (disabled until a board is selected), or call POST /v1/jira/app/sync from a signed-in owner or admin session. The call returns { "enqueued": true }, re-runs the 30-day backfill and re-registers any missing or expired webhook.

Jira ticket events and comments by nima

With outbound dispatch on for the workspace, Jira also produces ticket events and nima can propose comments on tickets. Both need dispatchEnabled set on the workspace, and rules need triggersEnabled too. Ask the nima team if you cannot make the settings call.

Ticket events from Jira

Jira is the only source of ticket events. nima records three, never as cards:

The comment_created webhook is registered only while dispatch is on and a Jira writer is connected. nima's own comments never become events. Workspace rules over these events, such as an assignee reminder DM or an agent that drafts a reply, are described in Watches and reminders. Every proposed comment goes through Outbound actions: it waits for approval on its card unless the workspace's action policy lets it post automatically.

Jira writer modes

The Jira writer is the identity nima comments as. An owner or admin configures it with POST /v1/integrations/jira/writer, from a signed-in session or with an API key that carries integrations:write. Read the current state with GET /v1/integrations/jira/writer.

Use a service account. The Jira connection's consent screen does not ask for the comment scopes, so a connector_fallback writer shows write:comment:jira, write:comment.property:jira and read:comment.property:jira in missingScopes. nima refuses to propose comments through it, and comment events are never registered for it. Until the connection asks for those scopes, connector_fallback cannot post.

The service-account API token needs the scopes write:comment:jira, write:comment.property:jira and read:comment.property:jira, plus read:comment:jira to receive comment events. The response lists scopes and missingScopes and never returns the credential. nima cannot inspect an API token, so for a service account scopes lists what you were asked to grant, and a token missing a scope shows up only when a comment fails. The MCP tool connect_jira_writer reports status and toggles the binding but never accepts a token: a service account is connected only through the REST route. An API key gets the integrations:write scope from the Slack command /nima mcp-key integrations, run by an owner or admin. Full request and response fields: Writers API. MCP tool: Outbound tools.

Every comment ends with a line naming who nima acted for, and carries a comment property that lets nima recognize its own posts.

Jira limits

• One Jira site and one board per workspace. Switching boards re-syncs.
• Backfill: 30 days and 200 issues. The webhook watches the first 50 projects.
• Write-back to Jira is status transitions, plus comments through approved outbound actions. nima creates no issues and edits no fields.
• The status mapping cannot be edited.
• The On/Paused switch on the Jira row in Integrations only changes a label; it does not stop the sync. Disconnect to stop it.
• If Atlassian access is revoked or expires, connectionInvalid is true and reading and writing stop until someone reconnects.

Disconnect Jira

Disconnecting Jira stops the sync and removes the installation, its webhooks and its issue links. Press Disconnect on the Jira row in Integrations, or call DELETE /v1/integrations/jira from a signed-in owner or admin session. nima makes a best effort to delete its webhooks at Jira. It does not revoke the grant in your Atlassian account, so remove nima from your Atlassian connected apps if you want the token gone. Cards already on the board stay, and nothing is changed or deleted in Jira.

Disconnecting does not delete a Jira writer. If you connected a service account, first turn the writer off with POST /v1/integrations/jira/writer and { "mode": "service_account", "enabled": false }, because that route stops working once Jira is disconnected. Then revoke the service account's API token in Atlassian.