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.
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:Step 1: Collect your provider’s details
Gather these first. In step 2 you pass them as flags, and the secret on stdin.- Jira
- Linear
- Webhook
You need four values, plus one optional one.That account needs these permissions in the target project, or deliveries fail with a Jira
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.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.
- Jira
- Linear
- Webhook
--issue-type to create Task issues.--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.
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:
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 JSONPOST 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 aboveX-Ankra-Delivery- a unique id for this delivery attemptX-Ankra-Signature-sha256=<hex>, present only when the connection stores a signing secret
ticket.created body:
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,chorepriority-urgent,high,medium,lowstatus-triage,investigating,planning,awaiting_review,awaiting_approval,executing,verifying,done,blocked,cancelledevent_type-comment,status_change,assignment,plan_draft,review,session_linked,workspace_linked,link_added,thread_message,resolution,run_outcomeauthor_kind-agent,user, or the board itselfpayload- the raw members of that event type, such asfrom_statusandto_statuson a status change,verdicton a review,resolutionon 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 withsha256=. 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 -
--disablestops deliveries without losing the configuration or the cursor.--enableresumes 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-scopeand the other flags ofcreate. A connection cannot change provider: create a second connection instead. -
Rotate the credential -
--rotate-secretwith--secret-stdin, or a hidden prompt, replaces the stored secret. For Jira, pass--emailwith 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;--yesskips the question.
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.
Related pages
- AI Board - ticket kinds, statuses, priorities, and the plan approval flow
- Work the AI board with your own agent - act on tickets over MCP, the way back in that sync does not provide
- AI Connections - the Slack, Teams and code host connections on Gateway connections
- Webhooks - alert and platform event destinations, a separate system from ticket sync
- Roles and Access - who counts as an organisation admin