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.
Cloud vs Data Center
Section titled “Cloud vs Data Center”| 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) |
Create credentials
Section titled “Create credentials”- Open
https://id.atlassian.com/manage-profile/security/api-tokens(the Create an API token link in Jimothy’s sign-in dialog). - Click Create API token, give it a label such as
Jimothy, pick an expiry, and copy the token. - 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. - 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.
- In Jira, open your avatar → Profile → Personal Access Tokens, and click Create token. (Personal access tokens are available on Jira Data Center / Server 8.14 and later.)
- Name it, set an expiry, and copy the token.
- In Jimothy: Settings → Accounts & integrations, Sign in under Jira. Set Jira site URL to your Jira base URL, e.g.
https://jira.acme.internal(include the context path if Jira runs under one, likehttps://acme.internal/jira), choose Data Center / Server — personal access token, and paste the token into API token. There’s no email field in this mode. - Click Sign in.
Username/password Basic authentication against Data Center isn’t supported; use a personal access token.
Sign-in calls /rest/api/<v>/myself to verify the credentials. The account’s workspace is recorded as the site host.
Trigger fields
Section titled “Trigger fields”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. |
Project and JQL together
Section titled “Project and JQL together”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.
JQL examples
Section titled “JQL examples”-- The default: anything labelled jimothy that isn't done, oldest firstlabels = 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 userassignee = "jimothy-bot" AND statusCategory = "To Do"
-- Only bugs in the current sprintproject = API AND issuetype = Bug AND sprint in openSprints() AND labels = jimothy
-- Recently created, to avoid picking up a backlog on day onelabels = jimothy AND created >= -7d AND statusCategory != DoneWhat the run sees
Section titled “What the run sees”| 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 |
Webhooks
Section titled “Webhooks”Jira triggers also accept Jira webhooks for instant starts when the webhook server is enabled (see Webhooks).
- Enable Settings → Accounts & integrations → Webhook server and expose it through a tunnel.
- Save the trigger and set a Webhook secret (any random string).
- 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. - 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>.
Write-back
Section titled “Write-back”- 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.