ADR-0008: Durable change processing and changed-file review triggers
- Status: Accepted
- Date: 2026-09-14
Context
Classification looked only at the pull request title, labels, and description.
A pull request titled chore: tidy that edits a database migration, the
security configuration, or a CI workflow could be settled by the rules and
released without anyone looking at it. GitHub's pull_request webhook carries
the number of changed files, never their paths, so listing them needs a
separate, authenticated GitHub call. That call must not run inside the webhook
request, which GitHub abandons after ten seconds, or inside a database
transaction. It must also survive restarts and transient GitHub failures.
Decision
- Each Project's GitHub integration may hold one access token. Only
administrators set it, it is optional, and it is write-only: a new token
replaces the old one, and reads only report whether one exists and when it
was set. Before storing it, ReleaseFlow calls
GET /repos/{owner}/{repo}/pulls?state=closed&per_page=1, which proves the permission the worker needs (reading pull requests), not merely that the repository is visible. The token is encrypted like the webhook secret, with agithub-access-tokenpurpose line added to the authenticated data. - Webhook intake records the change as
PROCESSING(Unknown and in review) and aPENDINGrow inchange_processing_jobsin one transaction. - Processing uses one table per kind of work, claimed with
FOR UPDATE SKIP LOCKEDby a scheduled worker. Claiming, the GitHub call, and recording the result are three separate steps, and the network call runs between the transactions. A claim is valid only while its time matches the job row, and jobs leftENRICHINGfor ten minutes are claimed again. - Timeouts, network errors, rate limits, and 5xx responses are retried after 2
and 4 seconds, up to three attempts. After that, and immediately when there
is no token, when GitHub refuses the token, when the response is invalid, or
when five pages of 100 files are all full, the change is still classified,
with a
CHANGED_FILES_UNAVAILABLEreview trigger. A truncated list is never treated as complete. - A changed path, or the previous path of a rename, that matches a configured
JDK glob adds a
SENSITIVE_PATHtrigger. The deployment's pattern list (RELEASEFLOW_SENSITIVE_PATHS) has a default baseline. An invalid pattern or an empty list stops startup, so the rule cannot be disabled by accident. - Review triggers only add a need for review. Only a recorded human review clears it, and the trigger is kept. A documentation-only file list selects the Documentation category, ahead of the title type.
- Only two trigger types exist. Keyword triggers are for sources without file lists and wait for those sources.
Consequences
- Without a token, every new change needs review. This is deliberate: nothing can be ruled out.
- A change is briefly
PROCESSINGand cannot be reviewed, sent to AI, or released meanwhile.changes_processing_unsettledandchanges_triggers_require_reviewenforce this in PostgreSQL as well. - Changes recorded before Flyway
V10keep their classification and are never processed. - The worker runs in every application instance.
SKIP LOCKEDmakes that safe without a leader, and later kinds of work reuse the same pattern in their own tables. - Configured patterns are split on commas, so brace groups such as
{a,b}cannot be used.