Jira

A Jira trigger runs a JQL query against your Jira site on a poll 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

	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

Jira Cloud

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: Accounts → 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 your JQL covers, plus Add comments and Transition issues if you use write-back.

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

Data Center / Server

1. 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.)
2. Name it, set an expiry, and copy the token.
3. In Jimothy: Accounts → 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, like https://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.
4. 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

Open Triggers → Add trigger → Jira.

Field	Stored as	Notes
Name	name
Runs pipeline	pipelineId
Jira account	connectionId	Required.
JQL	jira.jql	Required. 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.
Webhook secret	webhook.secret	Shared token for Jira webhooks (below).
Write back to the issue	onStart, onSuccess, onFailure	Comment and/or transition.

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.

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

JQL examples

-- The default: anything labelled jimothy that isn't done, oldest first
labels = jimothy AND statusCategory != Done ORDER BY created ASC

-- One project, a specific status used as the hand-off
project = WEB AND 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

Tip

Make your JQL exclude the status your start write-back moves issues to (for example status = "Ready for AI" plus an on-start transition to In Progress). Issues then leave the query as soon as a run starts.

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

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

1. Enable Settings → 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.

The trigger's JQL doesn't filter webhook events

Jimothy doesn’t re-run your JQL for webhook deliveries. Any issue in a Jira webhook payload is treated as a match (subject to dedup). Put the same filter on the Jira webhook’s own JQL setting, or rely on polling alone.

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

• Comment posts the start message or run summary. On Cloud the text is converted to ADF paragraphs with line breaks.
• The transition field takes a transition name or a target status name, matched case-insensitively against 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.