Jira add-on mode

Added in v0.235.0 In add-on mode you keep Jira Cloud as the ticket system your team works in. orboto runs next to it for everything agents do: work sessions, claims, mandates, review, approval and the audit trail. One orboto project is linked to one Jira project, and a JQL scope decides which Jira issues come in. You bring in the agent work, not the whole backlog. To move a whole Jira site to orboto instead, see the whole-site Jira import. The same mode exists for Linear.

What the link does

Work sessions, claims, mandates, review lanes, approvals and the audit trail stay in orboto. Status, comments and time stay editable in both places.

What reaches orboto from Jira after the first import:

• A status change in Jira moves the ticket.
• A new comment written in Jira reaches the agents of the ticket like a comment written in orboto: it wakes the specification agent and the live sessions of the assignees. The comments of the first import are history and wake nobody.
• Edited comments are updated. A comment deleted in Jira is removed from the orboto ticket too; a comment orboto wrote to Jira is never removed by that.
• New worklogs and new attachments are added to the ticket.
• If someone edits the description in Jira of a ticket whose specification was already released, the ticket goes back to Needs specification, as if the description had been edited in orboto.

Before you start

• The orboto project carries the same key as the Jira project (for project ALPHA, the project key is ALPHA). The mirrored tickets keep their Jira keys. A different key is refused and the message names both keys.
• If the project already holds tickets, you confirm the merge by typing the project key when you link.
• You need the Edit project permission in orboto.
• The Jira site is an address like https://<site>.atlassian.net. It must be an https address without credentials in it.
• For live updates Jira needs to reach your orboto instance over HTTPS. Self-hosted: set API_PUBLIC_URL to the public address of your API; the webhook address and the sign-in return address are built from it. Without a webhook, orboto still picks up every change within 10 minutes.

Link a project

Added in v0.235.0 Open Project settings > Connectors, choose Jira as the ticket system and pick how orboto signs in:

• Atlassian sign-in (OAuth). You grant orboto access in Atlassian; the grant must include the Jira site you entered. orboto asks for read and write access to Jira work, read access to users, the right to manage webhooks, and a refresh token; tokens renew themselves and the webhook is registered for you. Your administrator enables this option once for the instance with an Atlassian OAuth 2.0 app (ATLASSIAN_OAUTH_CLIENT_ID and ATLASSIAN_OAUTH_CLIENT_SECRET); the app's callback address is <API_PUBLIC_URL>/connectors/jira/oauth/callback. Without that app only the API token is offered.
• API token. Create a token in Atlassian under Account settings > Security > API tokens and enter it with the email of that account. The account needs to browse, edit and transition issues, add comments and log work in the Jira project. With the token of a Jira admin, orboto also registers a signed admin webhook; without admin rights there is no webhook and the link works on the 10-minute check.

Enter the Jira site, the Jira project key and the scope, then choose Link and start the import. For OAuth, choose Continue to Atlassian and approve within 15 minutes; until then the link shows "Waiting for consent". orboto checks the credential against the project, registers the webhook, suggests the status mapping and imports the issues your scope selects. The import is a run of the Jira site import, limited to the one linked project, with its people mapping and field handling; it is not a second import path.

From the command line, the token is read from standard input only:

printf '%s' "$JIRA_TOKEN" | orboto connector connect --project ALPHA \
  --site https://acme.atlassian.net --jira-project ALPHA \
  --email bot@acme.example --scope "labels = agent"

With --oauth instead of --email, the command prints the address to open in a browser. An OAuth login to orboto itself (for example an AI client connected by OAuth) cannot create the link or replace its token, because both take a secret: use the web app, or a CLI profile with an API key.

Choose the scope

Added in v0.235.0 The scope is a JQL filter. orboto combines it with the project, so labels = agent mirrors the issues of the linked Jira project that carry the label agent. An empty scope mirrors the whole project. orboto does not check the JQL itself; Jira does when it runs.

An issue that enters the scope is imported. An issue that leaves it (it is edited so that it no longer matches) stops syncing, and so does one that is deleted in Jira; the orboto ticket stays in both cases and the ticket shows "Left the Jira scope" or "Deleted in Jira". orboto sees a deleted issue when an event or a write-back meets "not found"; the check every 10 minutes cannot tell a deleted issue from one that left the scope and treats it as having left the scope.

Map the statuses

Added in v0.235.0 Each orboto status category (to do, in progress, in review, done, won't fix) maps to one Jira status. orboto suggests the mapping from the status categories of your project and the status names (names with review, QA or test suggest "in review"; names like won't do, cancelled, rejected, declined, duplicate, invalid or abandoned suggest "won't fix"); change it in the Status mapping of the link. A category without a Jira status stays in orboto. The card marks a problem: a category that is not mapped, a status the Jira project does not have, or a status no mirrored issue can reach.

When a ticket moves in orboto, orboto asks Jira for the transitions of the issue and takes the one that ends in the mapped status. If no transition of the issue leads there from where it stands, orboto does not guess a path: that write-back is given up and shows in the delivery log as transition_unreachable. When two orboto statuses share one Jira status, they never flip each other.

What goes back, and when

Added in v0.235.0 Under Goes back to Jira you switch each kind on or off: status, comments, worklogs, pull request links and review decisions.

• A ticket has at most one status write waiting, and it sets the status the ticket has at the moment it is sent.
• A worklog is at least one minute long, notifies nobody in Jira and leaves the remaining estimate of the issue as it is.
• A pull request keeps one remote link on the issue; when the pull request is merged or closed, the same link turns resolved.
• A write that fails is tried again with growing waits (30 seconds, doubling up to 6 hours) and given up after 8 tries. When Jira asks orboto to slow down, orboto waits for the time Jira names and spends no try. When Jira refuses the credential, the link stops (see below). Other permanent refusals from Jira (bad request, forbidden, not found) are given up at once, and "not found" also unlinks the issue.

Keep an eye on the link

Added in v0.235.0 The link card shows its health: the last webhook, the last check, the number of mirrored and unlinked tickets, write-backs waiting, failed or given up, and the reasons when something needs attention (paused, credential refused, stopped, no webhook, webhook registration failed or expired, a webhook signature was rejected, calls fail, write-backs given up, the check has not run lately). The Delivery log lists what went to Jira and what came from it; a write-back that was given up can be retried.

• Sync now runs the check at once. It answers "try again in a moment" while the last check is less than 60 seconds old.
• Register webhooks again replaces the webhooks of the link.
• Pause stops intake, check and write-back; Resume continues.
• With an API token, Replace token checks the new token against the project and revives a link that Jira had refused. With OAuth, Authorize again starts a new consent.
• When Jira refuses the token or the sign-in, the link stops and the project admins get a notification; replace the token or sign in again. They also get one when the link keeps failing, and another when it recovers.
• Admin > Integrations > Add-on connectors lists every link of the workspace (needs admin:system:read).
• On a mirrored ticket, a Mirrored from Jira line names the issue and the fields Jira owns.

If the first import stops, the card shows the reason under Last problem. A Jira link has no retry for its initial import: the Retry the initial import button on a stopped Jira link answers "A Jira link has no retry for its initial import" (the first import is a run of the Jira site import). To start again, unlink the project and link it again; unlinking keeps every ticket, and a project that holds tickets needs the merge confirmation.

Unlinking removes the webhooks in Jira and stops the sync. Every mirrored ticket stays in orboto and is an ordinary ticket again.

Limits of the Jira APIs

• The webhooks of an OAuth link carry no worklog events. Worklog changes reach those links with the next issue update and the 10-minute check. Webhooks of an OAuth link expire after 30 days; orboto renews them a week before.
• Atlassian allows 5 webhooks per OAuth app, user and site. Each link holds one, so one person who consents can link 5 projects of a site. A further link reports a webhook error; another person consents for it.
• An attachment added to an issue after the first import is imported when its file name is new on the ticket.