ADR-0019: Jira sources and linked context
- Status: Accepted
- Date: 2026-09-17
Context
ADR-0018 made Linear the third source type and the first issue tracker. Jira is the fourth and last planned source, and it differs from every earlier one in three ways the model could not express:
- Nobody triggers it. The old project polled Jira every five minutes. Every
job row ReleaseFlow wrote until now existed because something else happened —
a delivery, an administrator's click, an approval — and
source_sync_jobs.requested_bywasNOT NULL. - It has no webhook.
webhook_id,secret_nonce, andsecret_ciphertextwereNOT NULL. - It explains other sources' changes. A GitHub or GitLab change should show the Jira issues it mentions, which needs a different source's credentials, and most mentions are in commit messages, which neither client could list.
S13 and S14 both deferred commit-message collection to this slice, and the
eighth and last review trigger of the old project, LINKED_CONTEXT_UNAVAILABLE,
depends on it.
Decision
-
A poll is a sync job nobody asked for. It reuses
source_sync_jobsasjob_type = 'JIRA_POLL', so claiming withSKIP LOCKED,Retry-After, backoff, stale recovery, and the one-active-job index all apply unchanged.requested_byandrequester_nameare nullable, andsource_sync_jobs_requester_matches_typesays only an import has them. A poll'sitem_limitisInteger.MAX_VALUE, so it never stops part-way. -
The schedule lives on the source.
poll_cursor_atandnext_poll_atare set when the source is connected (cursor = now, first poll one interval later, so nothing before the connection is read). Each tick of the renamedSourceSyncWorkerfirst asksJiraPollSchedulerfor sources whosenext_poll_athas passed and that have no active job, and inserts one poll for each with the window[poll_cursor_at − 10 minutes, now]. The overlap costs nothing, because intake keeps one change per issue. A completed poll moves the cursor to the window's end and books the next poll one interval later; a failed one keeps the cursor, marks the sourceERROR, and comes back — after the job's own retries, or 15 minutes after a final failure. -
The cursor is opaque to the worker.
ImportCursor(page, offset)becomesSyncCursor(provider, offset), stored asprovider:offsetand split at the last colon. GitHub and GitLab put a page number in the provider half (blank is the first page); Jira puts itsnextPageToken.provider_cursorwidens toVARCHAR(500). A row written before V21 (1:2) still parses. -
Only an Atlassian Cloud site.
JiraSiteUrlaccepts HTTPS, no userinfo, port, query, or fragment, and a host that isatlassian.netor ends in.atlassian.net. It is checked when connecting and again before every call; redirects are never followed, and a redirect answer confirms nothing. The deployment-onlyRELEASEFLOW_JIRA_API_BASE_URLsends every call to one fixed address instead — for tests and local runs — while the site a request named is still checked and still builds every issue link. -
Basic credentials, required. Jira takes
email:token, so a Jira source stores the account email incredential_identityand the API token encrypted as before. Both are required and checked withGET /rest/api/3/project/{key}before anything is written. -
An issue that is done is a change. The JQL is
project = "KEY" AND statusCategory = Done AND updated >= "yyyy-MM-dd HH:mm" ORDER BY updated ASC, 100 at a time. The window is judged onresolutiondate, falling back toupdated, so an old issue that was merely edited is skipped. The number in the key is the change's number, Jira's internal ID itsexternal_id, the title isKEY-123: summary, the author the reporter's display name, and the URL{site}/browse/KEY-123, built by ReleaseFlow. The description is Atlassian Document Format, flattened to at most 8000 characters. A poll's changes are recorded with originIMPORT, the only non-delivery origin there is. -
Linked context is a second enrichment step.
SourceEnricherstays as it was for the three existing providers. After it,LinkedContextEnricherfinds the Project's Jira source by type (the oldest, if there are several), reads the change's commit messages through a newSourceEnricher.commitMessages(...)(GitHub and GitLab only, at most 250, over three pages), and extracts the Jira project's keys from the title, description, target branch, and commits with the old project's pattern(?<![A-Z0-9_])(KEY-[1-9][0-9]*)(?![A-Z0-9_-]), case-insensitive, at most ten. Each key is fetched withGET /rest/api/3/issue/{key}. -
Six statuses, two of which ask for a person.
Status When NOT_SUPPORTEDThe change's own source is Linear or Jira NOT_CONFIGUREDThe Project has no Jira source with a token, or the change's own source has no token NOT_FOUNDCommits were read and no key was found PARTIALCommits could not be read, so a key may have been missed UNAVAILABLEA key was found and Jira would not show that issue COLLECTEDCommits were read and every key resolved PARTIALandUNAVAILABLEare retried on the same budget as the source's own enrichment, so the change stays visibly Processing, and once attempts run out they addLINKED_CONTEXT_UNAVAILABLE. The trigger is raised byChangeClassifier, besideCHANGED_FILES_UNAVAILABLE, rather than inChangeAiMergeas first planned, because the classifier already turns an external outcome into a trigger and this covers the AI-disabled path too. -
Issues are evidence, commit messages are not even that. A change stores its issues in
linked_issuesand its status inlinked_context_status; the AI prompt gets a top-levellinked_issuesarray marked untrusted, and its response schema is unchanged. Commit messages are used to find keys and are never stored or sent to the AI. -
Release notes may list issues. Audience templates gain an additive
linkedIssuessection withkey,title,type,status, andurl. The description is left out on purpose, and every tracker value but the URL is escaped. The seeded templates do not use it, so no template migration is needed.
Consequences
- ReleaseFlow now does work on its own schedule. It is still a job row, visible and retried like any other, and the Change Inbox shows each Jira source's last and next read instead of an import button.
- Every planned source exists, and parity milestone M2 is reached.
- A Jira change's title starts with its key, so the Conventional Commit title rule never matches one; without AI, a Jira change is Unknown and needs review. The old project behaved the same way.
- The key pattern rejects a key followed by a hyphen, as the old project's did,
so a branch named
feature/APP-3-exportnames no issue. A commit or title that mentionsAPP-3still does. - A Project with several Jira sources is enriched from the oldest one only.
- Only Jira Cloud is supported. Jira Server or Data Center, and Jira webhooks, are out of scope.
- A poll that fails for good waits 15 minutes before the next one, and the
source shows
ERRORuntil one succeeds.