Skip to main content
connic
Connectors

Jira

Start agents when issues are created or updated or comments are added in Jira Cloud, and post their results as comments or new issues.

Last updated
ModesInbound, outbound
YAML typejira
CredentialsA Connection of type jira with the site URL, account email, and API token of an Atlassian account
SitesJira Cloud. Jira Data Center and Server aren't supported.
BridgeNot supported
Custom domainNot supported
Linked agentsOne or more. A matching event starts every linked agent.
While pausedEvents get 200 and start no runs; the webhook stays in Jira. Outbound sends nothing.

Set up

  1. Create an API token without scopes for the Atlassian account your agents act as. For inbound connectors, the account needs the Administer Jira global permission.

  2. Open the agent. In Connector Flow, click Add inbound connector for issue events or Add outbound connector for comments and issues. Then click Create New Connector and choose Jira.

  3. Choose the mode. Under Connection, pick a saved Connection or create one with the Site URL, Account email, and API token.

  4. For inbound, enter the Events, one per line, and the JQL filter. For outbound, enter the Project key and the Issue type.

  5. Click Create. An inbound connector registers its webhook in Jira. For outbound, choose how the agent uses the connector and click Link connector.

In code

Declare the connector in connectors/*.yaml. connection names the Connection that holds the site and the account's API token.

connectors/support-issues.yaml
type: jira
mode: inbound
connection: acme-jira   # Connection with the site, account email, and API token
config:
  events:
    - jira:issue_created
    - comment_created
  jql: project = SUP
agents:
  - support-triage
connectors/support-comments.yaml
type: jira
mode: outbound
connection: acme-jira
config:
  project_key: SUP
  issue_type: Task
agents:
  - name: support-triage
    outbound: { usage: automatic }

Configuration

The fields of a Jira connector, the same in connectors/*.yaml, the REST API, and connic MCP. The descriptions name the matching setting in the dashboard. Connectors in code describes the fields every connector shares, such as agents and environments.

FieldTypeStatusDescription
typestringRequiredjira.
modestringRequiredinbound or outbound. Dashboard: Mode.
connectionstringRequiredName or ID of a Connection of type jira. See Atlassian account. Dashboard: Connection.
configobjectRequiredJira settings.
eventsstring[]RequiredInbound. The events that start runs: jira:issue_created, jira:issue_updated, and comment_created. Dashboard: Events, one per line, starting with jira:issue_created.
jqlstringRequiredInbound. Only events of issues that match this JQL start runs, such as project = SUP or project = SUP AND issuetype = Bug. Dashboard: JQL filter.
project_keystringRequiredOutbound. The project of new issues, such as SUP. Dashboard: Project key.
issue_typestringRequiredOutbound. The type of new issues, as named in the project, such as Task or Bug. Dashboard: Issue type.Default: Task

The site URL, account email, and API token belong to the Connection, not to the connector. Creating or saving a connector checks them with Jira, and for outbound also the project and issue type.

Agent input

Modes: Inbound

An inbound connector starts a run for every linked agent each time one of its events happens on an issue that matches its JQL filter. Events the Connection's account causes itself, such as the agent's own comments and issues, are ignored, so agents don't trigger themselves. The run receives:

payload.json
{
  "event": "comment_created",
  "issue_key": "SUP-42",
  "project": "SUP",
  "conversation_id": "jira:acme.atlassian.net/10042",
  "summary": "Checkout fails for EUR orders",
  "text": "Still happening after the last deploy.",
  "url": "https://acme.atlassian.net/browse/SUP-42?focusedCommentId=10310",
  "author": "Jane Doe",
  "author_account_id": "5b10ac8d82e05b22cc7d4ef5",
  "raw": { ... }
}
  • event is Jira's event name, such as comment_created.
  • issue_key, project, and summary describe the issue, also for comments.
  • conversation_id stays the same for every event of one issue, also after it moves to another project. To give the agent the earlier events as history, set session.key: input.conversation_id in its YAML; the connector doesn't turn on sessions by itself.
  • text is the comment for comment_created and the issue's description otherwise, as Jira sends it. url links to the issue or comment.
  • author and author_account_id name the person who created or changed the issue or wrote the comment.
  • raw is Jira's full event payload as sent, with the changelog of jira:issue_updated.

An event that Jira delivers again doesn't start another run. Inbound mode doesn't reply by itself: to comment on the issue, link the agent to an outbound Jira connector that uses the same Connection; see Outbound delivery.

Atlassian account

Connectors read and write in Jira as the account of the Connection. Use an account just for your agents: events that this account causes never start runs, so your own comments wouldn't reach the agents if the Connection used your account.

Connection fieldDescription
Site URLYour Jira Cloud site, such as https://acme.atlassian.net.
Account emailThe email of the Atlassian account the API token belongs to. Connectors read and write in Jira as this account.
API tokenAn API token of that account, created without scopes.

Sign in as that account, open API tokens in the Atlassian account settings, and choose Create API token, not Create API token with scopes. Jira rejects tokens with scopes on the site URL and when registering webhooks. Atlassian lets API tokens live for at most 365 days; see Manage API tokens for your Atlassian account. Before the token expires, create a new one and enter it on the Connection in Project Settings → Connections. Every connector that uses the Connection picks it up.

Inbound connectors need the Administer Jira global permission, because connic registers a webhook on the site when you save the connector. Each inbound connector has its own webhook, named connic connector with the connector's ID, under System → WebHooks in Jira. Changing the events or the JQL filter updates it, and deleting the connector removes it. connic checks the signature of every event with a secret it generated for the webhook. Outbound connectors need permission to browse the project, add comments, and create issues.

Outbound delivery

Modes: Outbound

An outbound Jira connector posts once each time it's used: when a linked agent's run completes, when the model calls it as a tool, or when middleware calls it, depending on the link's usage. The first rule that applies decides where:

  1. When the output or payload sets issue_key, it comments on that issue.
  2. When the run came in through a Jira inbound connector on the same Connection, it comments on the issue the run started from.
  3. Otherwise it creates an issue of the connector's issue type in its project. The summary is summary from the output or payload, or else the first line of the text.

The text becomes the comment or the issue's description as plain text: an empty line starts a new paragraph, and a line break stays a line break.

Automatic output

An automatic link posts the run's final output. Plain text becomes the text. A JSON object takes the text from body, text, message, response, or output, in that order, and can set summary and issue_key.

output.json
{
  "summary": "EUR totals are rounded twice at checkout",
  "body": "Orders in EUR are one cent off since 2.14.0.\n\nThe total is rounded in the cart and again at payment."
}

Agent-tool and middleware payload

The model or middleware passes body, which is required and can't be empty, and optionally summary and issue_key. Other fields are rejected.

connector-payload.json
{
  "body": "Reproduced: the total is rounded in the cart and again at payment.",
  "issue_key": "SUP-42"
}

Delivery and retries

When Jira rate-limits a comment or issue, connic waits and sends it again. The connector's runs show each delivery with the link to the issue, or with the error.

Limits and errors

LimitValue
API tokenExpires after 1 to 365 days, chosen when you create it, set by Atlassian. Replace it on the Connection before then.
Answer to Jiraconnic answers right away and runs the agents afterwards.
Failed deliveriesJira retries an event up to 5 times, 5 to 15 minutes apart, when connic answers 429 or 5xx or can't be reached.
Writes per issue20 per 2 seconds and 100 per 30 seconds, set by Jira. When Jira rate-limits, connic waits and retries the delivery.
Issue summary255 characters. A longer summary is cut.

Requests with a missing or wrong signature get 401. Creating a connector fails when Jira rejects the account email and API token, for example a token with scopes or an expired one, when an inbound connector's account lacks the Administer Jira global permission, or when an outbound connector's project or issue type doesn't exist. A delivery fails when Jira rejects it, for example when the issue doesn't exist or the account can't comment on it.

An expired token doesn't stop events from arriving, but deliveries and saving connectors fail until you replace it. When Jira can't be reached or rejects the token while you delete a connector, the connector is deleted anyway; remove its webhook in Jira under System → WebHooks.