Skip to main content
A sync connection mirrors AI board tickets outbound. Each ticket that matches the connection’s filters gets an issue created once in your tracker, and its timeline events follow as comments on that issue. Three providers are available: Jira, Linear, and a generic webhook. Sync is one-way. Ankra creates the issue, adds comments and keeps its title current, and never reads anything back: editing, commenting on, reassigning or closing the issue in Jira or Linear changes nothing on the board, and a status change on the board arrives as a comment rather than moving the issue’s own status. To act on a ticket from outside the portal, use the ticket’s Slack or Teams thread, ankra tickets, or your own agent over MCP. This is a different system from webhook destinations, which deliver alert firings and platform events. Sync connections carry board tickets only.

Prerequisites

  • You are an organisation admin. Members can see the connection list, but only admins can add, change, switch or delete one.
  • Tickets are turned on for your organisation: Ankra AI → Work is in the menu.
  • The Ankra CLI, logged in to the organisation. The portal has no page for sync connections: you create and manage them with ankra tickets sync.
  • The destination is reachable from the public internet.
Ankra dials sync destinations from its own infrastructure and refuses any address that is not publicly routable - loopback, private ranges, link-local (including the 169.254.169.254 cloud metadata endpoint), and IPv6 unique-local. A self-hosted Jira or a webhook receiver that only exists inside your VPN or cluster network cannot be reached. Literal private IPs are rejected when you save; a hostname that resolves to one is refused at delivery time and shows up as a failed delivery.

What gets synced

A new connection picks up your organisation’s live tickets plus anything that changes afterwards. The closed backlog stays out, so enabling Jira sync does not file a thousand finished tickets into a fresh project. Closed tickets only sync if they change again after the connection was created. Three filters narrow it further, each a flag on the connection:
--event-scope anchor_only is not a pause. The timeline cursor moves to the tail as tickets change, so events skipped while the connection is in this mode are skipped permanently. Switching back to relaying comments later resumes from that point and never backfills what was missed.

Step 1: Collect your provider’s details

Gather these first. In step 2 you pass them as flags, and the secret on stdin.
You need four values, plus one optional one.
1

Jira base URL

Your Jira site root, with no path after it - for example https://my-team.atlassian.net. Copy it from the address bar while you are in Jira, and drop everything from /jira onwards.
2

Project key

The short uppercase code for the project issues should land in. In Jira, open Projects and read the Key column, or take the prefix from any issue key in that project: OPS-123 means the key is OPS.
3

Issue type (optional)

The name of the issue type to create, exactly as it appears in Jira - Task, Bug, Story. It has to exist in that project’s issue type scheme. Leave the field blank to use Task.
4

Account email

The email address of the Atlassian account the API token belongs to. Issues and comments in Jira are attributed to this account, so a dedicated service account keeps your board traffic out of a person’s name.
5

API token

Sign in as that account, go to id.atlassian.com/manage-profile/security/api-tokens, and choose Create API token. Label it something you will recognise later, such as ankra-ticket-sync, then copy the token.
Atlassian shows the token once. Copy it before closing the dialog.
That account needs these permissions in the target project, or deliveries fail with a Jira 403:
  • Browse Projects - to address the project at all
  • Create Issues - the issue Ankra opens per ticket
  • Add Comments - the timeline relay
  • Edit Issues - Ankra pushes the ticket title onto the issue when it changes
Ankra talks to Jira over the REST v2 API using HTTP basic authentication, which is the Jira Cloud email plus API token shape. Jira Data Center serves the same API, so a Data Center username and password go in those same two fields - as long as the instance is reachable on the public internet.

Step 2: Add the connection

The secret is never an argument: pipe it on stdin with --secret-stdin, or leave the flag off in a terminal and the CLI asks for it with the input hidden. Ankra stores it in its secret store and never returns it.
Leave out --issue-type to create Task issues.
The name is for your own use, up to 200 characters, and unique within the organisation. A connection starts enabled, so live tickets begin syncing as soon as it is created. Add --disabled to review it, or brief the team, before anything lands in the tracker. You should see the connection printed with its Provider, Target, State and Credential. held by the platform (never shown) means Ankra holds the secret.

Verify it works

To confirm the wiring end to end, change something on a live ticket that matches the filters - move its status, or leave a comment. The sync loop runs every 30 seconds, so within about a minute Last synced shows a time and the issue exists in your tracker.
A large first batch drains over several passes rather than all at once: deliveries are throttled to stay under tracker rate limits, and each ticket relays up to 20 timeline events per pass. A busy board that has just been connected takes a few minutes to catch up.
From an MCP client, list_ticket_sync_connections lists the connections.

What lands in Jira and Linear

The issue title is [T-<number>] <ticket title>, matching the board’s per-organisation ticket number. The description opens with the classification, the cluster when the ticket names one, and a link back to the board, then the ticket body:
Timeline events then arrive as comments: status changes as Status: triage → **investigating**, peer reviews as Peer review: **approve**, resolutions as Resolved (**fixed**), comments prefixed with who wrote them. Chat thread messages are not relayed to Jira or Linear, to keep conversation noise out of the tracker. When a ticket’s title or priority changes without producing a timeline event, Ankra pushes the updated title onto the external issue.

Webhook payloads

Webhook connections receive JSON POST requests instead of rendered prose. Three event shapes exist, and each one carries the full ticket snapshot, so your consumer never needs a read-back call. A common consumer is a receiver that starts your own agent on each new ticket - see Start your agent from new tickets. Every request carries these headers:
  • X-Ankra-Event - the event name above
  • X-Ankra-Delivery - a unique id for this delivery attempt
  • X-Ankra-Signature - sha256=<hex>, present only when the connection stores a signing secret
A ticket.created body:
A ticket.event body adds the event alongside the same snapshot:
ticket.updated has the same shape as ticket.created with a different event value. Field vocabularies:
  • kind - incident, insight, gap, automation, request, chore
  • priority - urgent, high, medium, low
  • status - triage, investigating, planning, awaiting_review, awaiting_approval, executing, verifying, done, blocked, cancelled
  • event_type - comment, status_change, assignment, plan_draft, review, session_linked, workspace_linked, link_added, thread_message, resolution, run_outcome
  • author_kind - agent, user, or the board itself
  • payload - the raw members of that event type, such as from_status and to_status on a status change, verdict on a review, resolution on a resolution
Webhook consumers receive every timeline event, including the thread_message chat echoes that the Jira and Linear connectors skip. sequence is monotonic per ticket, so use it to order and de-duplicate.

Verifying the signature

The signature is the hex HMAC-SHA256 of the raw request body using your signing secret, prefixed with sha256=. Compute it over the bytes as received, before any JSON parsing or re-serialisation.

Manage a connection

ankra tickets sync connections update <connection-id> changes only what you pass:
  • Switch it off or on - --disable stops deliveries without losing the configuration or the cursor. --enable resumes from where it stopped, and anything that changed in the meantime is delivered then.
  • Change the target or filters - --project-key, --team-id, --url, --kind, --min-priority, --event-scope and the other flags of create. A connection cannot change provider: create a second connection instead.
  • Rotate the credential - --rotate-secret with --secret-stdin, or a hidden prompt, replaces the stored secret. For Jira, pass --email with it.
  • Retry a failing connection - an update that changes the settings or rotates the credential clears the failure and retries at once, rather than waiting for the next pass. Renaming, switching or filtering alone does not.
  • Delete - ankra tickets sync connections delete <connection-id> removes the connection and its stored credential. It asks first; --yes skips the question.
Deleting a connection stops the sync and cannot be undone. External issues that were already created are left exactly as they are in Jira or Linear - Ankra does not close or delete them. Adding the connection back later starts a fresh cursor and files new issues for the tickets that are live at that moment.

Troubleshooting

Failures are retried automatically on the next pass. A failing connection does not block the others, and one failing ticket does not starve the queue behind it.