Skip to content

Jira

A Jira trigger watches a Jira project, a JQL query, or both, polls your Jira site on an interval, and starts one run per new matching issue. It works with Jira Cloud and Jira Data Center / Server, can also receive Jira webhooks, and can comment on and transition issues when runs start, succeed or fail.

Jira Cloud Jira Data Center / Server
Authentication option Jira Cloud — email + API token Data Center / Server — personal access token
Credentials Atlassian account email + API token, sent as HTTP Basic Personal access token, sent as Authorization: Bearer
REST API v3 v2
Search endpoint GET /rest/api/3/search/jql GET /rest/api/2/search
Comments Atlassian Document Format (converted from plain text) Plain text
Descriptions ADF converted to plain text / light Markdown Used as-is (wiki markup)
  1. Open https://id.atlassian.com/manage-profile/security/api-tokens (the Create an API token link in Jimothy’s sign-in dialog).
  2. Click Create API token, give it a label such as Jimothy, pick an expiry, and copy the token.
  3. In Jimothy: Settings → Accounts & integrations, Sign in under Jira. Set Jira site URL to your site, e.g. https://acme.atlassian.net, choose Jira Cloud — email + API token, enter the Account email of the Atlassian account that owns the token, and paste the token into API token.
  4. Click Sign in.

The token has the same permissions as the account. That account needs Browse projects on the projects the trigger watches, plus Add comments and Transition issues if you use write-back. A processed label also needs Edit issues.

Use a regular API token. Jimothy calls your site URL directly, which is how regular (unscoped) API tokens work.

Sign-in calls /rest/api/<v>/myself to verify the credentials. The account’s workspace is recorded as the site host.

Open the project’s Triggers tab (or All triggers in the ⌘K palette), click Add trigger and choose Jira.

Field Stored as Notes
Name name
Runs pipeline pipelineId
When it finds an issue delivery Start a run (default), or Add to a board to put the issue on a board and run it when its turn comes.
Board boardId With Add to a board: the board the issue goes to.
Jimothy project projectId Optional. Files the trigger under a project in the sidebar.
Jira account connectionId Required.
Jira project jira.projectKey Optional. A dropdown of the account’s Jira projects; Any project (JQL only) leaves it unset. Scopes the search, webhooks and the Move to statuses.
JQL / Filter (JQL, optional) jira.jql Required without a Jira project; optional with one. Every matching issue starts one run. Default: labels = jimothy AND statusCategory != Done ORDER BY created ASC
Poll every (seconds) pollIntervalSeconds Default 120, minimum 15.
Run again when a processed issue is updated retriggerOnUpdate Uses the issue’s updated field. Hidden when Processed label is set.
Processed label claimLabel Optional. Added to each issue Jimothy starts a run for; issues with it are skipped, and removing it runs the issue again. No spaces. See Processed label.
Webhook secret webhook.secret Shared token for Jira webhooks (below).
Write back to the issue onStart, onSuccess, onFailure Comment and/or transition.

With a Jira project picked, the JQL box becomes Filter (JQL, optional) and Jimothy searches:

project = "WEB" AND (<your filter>) <your ORDER BY>

Any ORDER BY in your filter is moved to the end, so labels = jimothy ORDER BY created ASC becomes project = "WEB" AND (labels = jimothy) ORDER BY created ASC. With an empty filter the search is just project = "WEB", which picks up every issue in the project, so most triggers keep a filter such as a label or status.

If the project list can’t be loaded, the editor shows the error and a text box where you can type the project key instead. Triggers saved before this option existed have no project and behave exactly as before.

Each poll requests up to 50 issues with the fields summary, description, labels, priority, status, assignee, reporter, updated, issuetype, in the order your JQL specifies. If more than 50 issues match, the rest are picked up on later polls as earlier ones get processed (processed issues still count toward the 50 until they stop matching), so keep the JQL tight.

With a Processed label, don’t select that label in the JQL (labels = jimothy-ran), or every issue is skipped. Excluding it is fine: labels = jimothy AND labels != jimothy-ran.

Use Preview matching issues to run the JQL before saving. JQL errors are shown exactly as Jira returns them.

-- The default: anything labelled jimothy that isn't done, oldest first
labels = jimothy AND statusCategory != Done ORDER BY created ASC
-- A specific status used as the hand-off (pick the project in the Jira project field)
status = "Ready for AI" ORDER BY priority DESC, created ASC
-- Assigned to the Jimothy service user
assignee = "jimothy-bot" AND statusCategory = "To Do"
-- Only bugs in the current sprint
project = API AND issuetype = Bug AND sprint in openSprints() AND labels = jimothy
-- Recently created, to avoid picking up a backlog on day one
labels = jimothy AND created >= -7d AND statusCategory != Done
Template value From Jira
{{issue.key}} e.g. WEB-45
{{issue.title}} summary
{{issue.description}} description; Cloud’s ADF is converted to text with headings, lists, code blocks, quotes and links
{{issue.url}} <site URL>/browse/<key>
{{issue.labels}} labels, comma separated
{{issue.status}}, {{issue.priority}} status and priority names
{{issue.assignee}}, {{issue.reporter}} display names
{{issue.raw.issueType}} issue type name, e.g. Bug

Jira triggers also accept Jira webhooks for instant starts when the webhook server is enabled (see Webhooks).

  1. Enable Settings → Accounts & integrations → Webhook server and expose it through a tunnel.
  2. Save the trigger and set a Webhook secret (any random string).
  3. Copy the URL from the trigger’s Instant webhook box. For Jira triggers it already includes ?token=<secret>. Swap the host for your tunnel’s public URL.
  4. In Jira (System → WebHooks on Cloud, or Administration → System → WebHooks on Data Center), create a webhook with that URL and select issue created/updated events. Use a JQL filter on the webhook itself to limit which issues are sent.

Jira webhooks don’t carry a signature Jimothy verifies, so the secret is checked as a shared token: the ?token= query parameter, an X-Factory-Token header, or Authorization: Bearer <secret>.

  • Comment posts the start message or run summary. On Cloud the text is converted to ADF paragraphs with line breaks.
  • Move to lists the Jira project’s statuses in workflow order (GET /project/<key>/statuses), or every status on the site when no project is set (GET /status).
  • When the run reaches that row, Jimothy looks for a transition whose name or target status matches, case-insensitively, among the transitions available for the issue right now (GET /issue/<key>/transitions). If none matches, the error lists what’s available:
Write-back to WEB-45 failed: No Jira transition to "In Review" (available: In Progress, Done)

Jira workflows often only allow certain transitions from each status, so a transition that works from To Do may not exist from In Progress. See Write-back.