Architecture
Implemented shape
ReleaseFlow is one Spring Boot application built from one Maven module and packaged as one executable JAR, with no separately deployed frontend: the compiled stylesheet ships inside it. Code is grouped by product capability, and a capability starts with direct, readable classes and gains internal layers only when implemented behavior needs them.
| Package | Capability |
|---|---|
status | The public home page and GET /api/status |
account | Organizations, registration, members, invitations, sessions, the output language, the interface language, and the public changelog slug |
project | Projects, integration sources, their credentials, and webhook verification |
source | The provider-neutral vocabulary every source type shares |
github, gitlab, linear, jira | One API client per provider, shared by project, change, and (for GitHub) automation |
change | Webhook intake, imports and polls, change processing, classification, AI, review, the Change Inbox, sensitive paths, and review signals |
category | The category catalog and AI proposals |
audience | Audiences, their templates, and the release note languages |
translation | Translation jobs, the cache, the Organization glossary and its DeepL sync, and the DeepL client |
release | The release lifecycle, release notes, and publication |
automation | Rules, triggers, runs, and every delivery action |
changelog | The anonymous public changelog |
overview | The workspace overview and the remembered Project |
configuration | Security, error handling, localization, and shared web configuration |
Every page and REST endpoint calls the same application services; the endpoints are listed in REST API. Five scheduled workers do everything that talks to another system after a request has returned (see Background work).
REST and Thymeleaf registration call the same transactional application
service. Project REST and UI controllers likewise call the same Project and
integration source services. One short registration transaction creates an
Organization and its ADMIN AppUser, and publishes OrganizationRegistered,
which CategoryService and AudienceService handle in the same transaction to
seed the default categories and the preset audiences.
Passwords are encoded with BCrypt before persistence; neither the hash nor the
submitted password is returned.
Roles and invitations
Registration creates an ADMIN. Accepting an invitation creates a MEMBER in
the invitation's Organization. SecurityConfiguration limits these to administrators
by URL rule, for the pages and their REST counterparts alike:
- members and invitations (
/members/**,/api/members,/api/members/**,/api/invitations/**); - connecting a source, setting its token, and starting or resuming an import;
- writing a Project's sensitive paths;
- all of audiences (
/audiences/**,/api/audiences/**, reads included); - writing the category catalog, and all of
/api/category-suggestions/**; - writing the release note languages, the output language, and the slug;
- all of automation (
/automation/**,/api/automation/**).
InvitationService and MemberService check the principal's role again. Every other
authenticated path is open to members.
InvitationService issues a 32-byte base64url token, stores only its SHA-256
hash, and returns the raw token once with Cache-Control: no-store. An
invitation expires after releaseflow.invitations.ttl (seven days by default),
works once, and can be reissued or revoked. A pending invitation past its
expiry is reported as expired and recorded as such when touched again.
The acceptance link keeps the token in the URL fragment. /accept-invite is a
server-rendered form that a small script fills from the fragment; the review
step shows the Organization and email, and the accept step locks the
invitation row, creates the member account, and marks the invitation accepted.
Every unusable token receives the same error. See
ADR-0006.
Role changes and removal
ADR-0043. An account is one membership: an
app_users row has one Organization, and its email is unique among rows that are not
removed (app_users_email_unique, a partial unique index since V38). A row is never
deleted, because 21 composite foreign keys record who did what; 18 of them keep the
person's name as it was, and the rest read it from the row.
MemberService.changeRoleandremoveeach run in oneTransactionTemplatetransaction that first locks the Organization row (OrganizationRepository.lockById,SELECT … FOR UPDATE), then counts its active administrators and refuses withLastAdministratorException(409 member_last_administrator) when none would remain. Demoting an administrator and removing anyone revoke the pending invitations that person made. Each change raisesapp_users.session_versionand inserts amembership_changesrow with the changer's ID and name. Removal setsremoved_atandremoved_byand clearspassword_hash; the row keeps its name and email.- The constraint trigger
app_users_keep_an_administrator(deferred, on updates that changeroleorremoved_at) takes the same Organization lock at commit and raises when no active administrator remains, so two writers that each demote the other cannot both commit, through the service or not.MemberServicemaps that commit-time failure to the same409. MembershipSessionFiltersits in the main filter chain beforeAuthorizationFilterand is built there, never as a bean, so it is not also a servlet filter. For aReleaseFlowPrincipalit readssession_versionandremoved_atby ID and Organization; when the member is removed or the version differs from the one copied into the principal at sign-in, it invalidates the session and clears the context. An/apirequest then continues anonymous and meets the API entry point's401 authentication_required; a page is redirected to/login?ended. Form sign-in is the only authentication, and the other filter chains are stateless and authenticate no member, so this is every request a member can make.- Lookups by address — sign-in, registration, and invitations — read rows that are not removed, so a removed person can sign in nowhere, and their address can be invited again, which creates a new row.
Persistence and tenant boundary
PostgreSQL is the only supported database. Flyway owns the schema and starts at
V1; Hibernate uses validate and never creates or updates tables. Integration
tests use PostgreSQL 17 through Testcontainers and run the same migrations.
organizations
id (UUID PK)
name
output_language (BCP 47 tag, V11)
slug (one DNS label, unique across the deployment, V24)
created_at
app_users
id (UUID PK)
organization_id (FK -> organizations.id)
email (canonical, globally unique)
password_hash
display_name
role (ADMIN | MEMBER)
ui_locale (nullable: the browser decides, V27)
organization_invitations
id (UUID PK)
organization_id
email (canonical), token_hash (SHA-256 hex, unique)
status (PENDING | ACCEPTED | REVOKED | EXPIRED; one PENDING per email)
expires_at, created_by / accepted_by (composite FKs -> app_users)
created_at, updated_at, accepted_at, revoked_at
projects
id (UUID PK)
organization_id (FK -> organizations.id)
name
created_at
context (V30, at most 2000 characters), context_updated_by (composite FK -> app_users), context_updater_name, context_updated_at
project_sensitive_paths (V16)
project_id (PK; composite FK with organization_id -> projects, ON DELETE CASCADE)
additional_globs (jsonb array, at most 100)
updated_by (composite FK -> app_users), updater_name, updated_at
integration_sources (github_integrations before V18)
id (UUID PK)
organization_id
project_id (composite FK with organization_id -> projects; several per Project)
source_type (GITHUB | GITLAB | LINEAR | JIRA) + external_project_key
(owner/repository, group/project, a Linear team, or a Jira project key;
unique per Organization and source type among connected sources, and per
Project whether connected or not, V37)
repository_owner + repository_name (GitHub only)
api_base_url (GitLab: an allowlisted instance; Jira: an atlassian.net site)
external_workspace_key (Linear only, the workspace the team belongs to)
external_team_key (Linear only, V35: the key its identifiers start with, such as OPS;
read at connection, or at the first enrichment of a team connected before)
credential_identity (Jira only, the account email of its Basic credentials)
webhook_auth_mode (GITHUB_HMAC | GITLAB_SIGNING_TOKEN | GITLAB_SECRET_TOKEN
| LINEAR_HMAC | NONE), which must match the source type (NONE is Jira's)
webhook_id (globally unique; while connected, null exactly when the mode is NONE)
secret_nonce + secret_ciphertext (present exactly when webhook_id is)
secret_updated_at (V37: when the secret was last set; failures count from here)
token_nonce + token_ciphertext + token_updated_at (the access token, V10)
poll_cursor_at + next_poll_at (Jira only: read up to here, read again then;
a disconnected Jira source keeps its cursor and has no next poll)
connection_status, last_sync_at, last_error_code
created_at
last_delivery_at (nullable, last accepted webhook delivery)
signature_failure_count + last_signature_failure_at (V37: deliveries whose
proof failed since secret_updated_at; written only by their own UPDATE)
disconnected_at + disconnected_by (V37, composite FK -> app_users; a
disconnected source has no webhook_id, secret, token, or next_poll_at)
changes
id (UUID PK)
organization_id
project_id (composite FK with organization_id -> projects)
source_id + external_id (unique: the source and its own ID for the change, V18)
source_type (matches the source through a composite foreign key)
origin (WEBHOOK | IMPORT)
pull_request_number (the provider's own number: a pull request, a merge
request, a Linear issue, or the number in a Jira key)
title, description, author_login (null when the source names no creator), labels (text[])
target_branch + merge_commit_sha (a code host's change only), head_branch (V31, a code host's change only, when named), merged_at, url
delivery_id (the delivery that recorded the change, when the provider named one)
received_at
processing_status (PROCESSING | COMPLETED)
changed_file_status (COLLECTED | UNAVAILABLE | NOT_SUPPORTED), changed_files (jsonb)
review_triggers (jsonb array of {type, detail})
category (code), category_display_name, category_group (snapshot of the catalog category)
breaking, security (V34), needs_review, classification_reasons (text[])
classification_source (RULES | AI | SUGGESTION | HUMAN), ai_status (NOT_REQUESTED | SUCCEEDED | FAILED)
ai_provider, ai_model, ai_failure, ai_attempted_at
reviewed_by (composite FK with organization_id -> app_users), reviewer_name, reviewed_at
excluded_by (V29, composite FK -> app_users), excluder_name, excluded_at, exclusion_reason (all or none)
neutral_summary (jsonb; migrationKind and limitations since ADR-0035), content_language, audience_narratives (jsonb, keyed by audience code)
summary_edited_by (composite FK with organization_id -> app_users), summary_editor_name, summary_edited_at
context_score (0-100), context_status (SUFFICIENT | INSUFFICIENT), context_reasons (jsonb); null when not assessed
linked_context_status (NOT_SUPPORTED | NOT_CONFIGURED | NOT_FOUND | PARTIAL | UNAVAILABLE | COLLECTED; null before V21)
linked_issues (jsonb array; only when the lookup got as far as PARTIAL, UNAVAILABLE, or COLLECTED)
change_processing_jobs (V10)
id (UUID PK); change_id unique, composite FK -> changes
status (PENDING | ENRICHING | CLASSIFYING | FALLBACK_REQUIRED | COMPLETED)
attempts, next_attempt_at, claimed_at, completed_at, last_error, created_at
source_sync_jobs (V18)
id (UUID PK); source_id composite FK -> integration_sources, ON DELETE CASCADE
job_type (HISTORICAL_IMPORT | JIRA_POLL)
status (PENDING | RUNNING | RETRY_SCHEDULED | COMPLETED | PARTIAL | FAILED;
one PENDING, RUNNING, or RETRY_SCHEDULED job per source)
window_start, window_end, provider_cursor
scanned_count, imported_count, item_limit, attempts, next_attempt_at, claimed_at
last_error, requested_by + requester_name (an import's requester; a poll has none)
created_at, completed_at
duplicate_candidates
id (UUID PK)
(change_id, organization_id, project_id) and (duplicate_of_id, organization_id, project_id) FK -> changes, ON DELETE CASCADE
change_id + duplicate_of_id unique, distinct; similarity (0-1), evidence (jsonb: title, content, paths)
status (OPEN | CONFIRMED | DISMISSED), decided_by (composite FK -> app_users), decider_name, created_at, decided_at
category_definitions
id (UUID PK)
organization_id (FK -> organizations.id)
code ([A-Z][A-Z0-9_]*, unique per Organization, fixed), display_name
category_group (FEATURE | FIX | PERFORMANCE | DOCUMENTATION | MAINTENANCE | OTHER)
system_category (only UNKNOWN; always active, group OTHER), active, created_at, updated_at
category_suggestions
id (UUID PK)
(change_id, organization_id, project_id) FK -> changes, ON DELETE CASCADE; change_id unique
proposed_code, proposed_name, proposed_group, rationale
status (PENDING_REVIEW | APPROVED | MAPPED | REJECTED), resolved_code
decided_by (composite FK -> app_users), decider_name, created_at, decided_at
audience_definitions
id (UUID PK)
organization_id (FK -> organizations.id); (id, organization_id) unique
code ([a-z][a-z0-9_]*, unique per Organization, fixed), display_name
communication_intent, template_body (Mustache, at most 10000 characters)
footer_template_body (V34, Mustache over the release's values; blank adds nothing)
preset, created_at, updated_at
retired_at, retired_by (composite FK -> app_users), retirer_name (V39; all three or none)
audience_status_changes (V39, only ever inserted)
id (UUID PK); (audience_id, organization_id) FK -> audience_definitions
kind (RETIRED | RESTORED), changed_by (composite FK -> app_users), changer_name, changed_at
audience_template_variants (V17)
id (UUID PK); (audience_id, organization_id) FK -> audience_definitions, ON DELETE CASCADE
language, template_body, footer_template_body (V34); audience_id + language unique
organization_translation_settings (V17)
organization_id (PK)
target_languages (jsonb array of 1 to 5 tags), updated_by, updater_name, updated_at
translation_jobs (V17, V28)
id (UUID PK); change_id composite FK -> changes, ON DELETE CASCADE
release_id (V28) composite FK -> releases, ON DELETE CASCADE; exactly one of the two
source_language, target_language, input_hash; change_id or release_id + target_language + input_hash unique
input (jsonb), context (V30, the Project's context it was asked with), output (jsonb, exactly when SUCCEEDED)
glossary_version (V33, the pair's glossary version it asked for; empty for none)
glossary_outcome (V33: applied | unsupported_language_pair | glossary_sync_failed | glossary_answer_untranslated)
status (PENDING | RUNNING | SUCCEEDED | FAILED), attempts, next_attempt_at, claimed_at
last_error, created_at, completed_at
translation_cache (V17)
organization_id + source_language + target_language + text_hash (PK; the hash covers the context and
the glossary version the text was translated with, if any)
translated_text, created_at
glossary_kept_terms (V33)
id (UUID PK); organization_id; term (1-100 characters, one line); organization_id + term unique
created_by (composite FK -> app_users), creator_name, created_at
glossary_translations (V33)
id (UUID PK); organization_id; source_language, target_language (primary languages, different)
source_term, target_term; organization_id + source_language + target_language + source_term unique
created_by (composite FK -> app_users), creator_name, created_at
translation_glossaries (V33)
organization_id (PK; locked by a sync), deepl_glossary_id, created_at
glossary_syncs (V33)
organization_id + source_language + target_language (PK)
wanted_version, synced_version, status (PENDING | RUNNING | SYNCED | UNSUPPORTED | FAILED)
attempts, next_attempt_at, claimed_at, last_error, updated_at
releases
id (UUID PK)
organization_id, project_id (composite FK -> projects)
version, summary
status (DRAFT | IN_REVIEW | APPROVED | PUBLISHED)
version unique per Project, ignoring case
created_at, updated_at, planned_release_at
upgrade_guide_url (V34, absolute http or https, at most 2000 characters)
previous_release_id (V34, composite FK with organization_id, project_id -> releases;
releases_previous_release_published: only a published release, never itself)
approved_at, approved_by (composite FK -> app_users), approver_name
published_at, published_by (composite FK -> app_users), publisher_name
release_changes
release_id + change_id (PK); change_id unique
(release_id, organization_id, project_id) FK -> releases, ON DELETE CASCADE
(change_id, organization_id, project_id) FK -> changes
added_at
release_changes_change_not_excluded (V29): BEFORE INSERT, refuses a change with excluded_at
release_change_reviews
release_id + change_id (PK)
(release_id, change_id, organization_id, project_id) FK -> release_changes, ON DELETE CASCADE
action (APPROVE | EDIT), note
reviewer_id (composite FK with organization_id -> app_users), reviewer_name, decided_at
folded_change_id (V36, composite FK -> changes: the tracker change whose fold made this
decision; cleared by a person's own decision)
linked_issue_reads (V35; one per release, queued when its review is requested)
release_id (PK); (release_id, organization_id, project_id) FK -> releases, ON DELETE CASCADE
status (PENDING | RUNNING | SUCCEEDED | FAILED), attempts, next_attempt_at, claimed_at,
last_error (a fixed code), requested_at, completed_at (exactly when finished)
release_linked_issues (V35; each linked issue of a release as of its review)
release_id + tracker (JIRA | LINEAR) + issue_key (PK); FK -> releases, ON DELETE CASCADE
status, status_category (open | done), read_at (together; null until read)
accepted_status, accepted_by (composite FK -> app_users), accepter_name, accepted_at (together)
release_fold_decisions (V35; once per release and tracker change)
release_id + tracker_change_id (PK); FK -> releases, ON DELETE CASCADE
tracker_change_id, code_change_id (composite FKs -> changes; never equal)
evidence (LINKED_KEY | CONFIRMED_DUPLICATE), issue_key
decision (ACCEPTED | DISMISSED); removal (REJECTED | EXCLUDED) exactly when ACCEPTED;
reason exactly when EXCLUDED
adds_breaking, adds_security (V36; only on ACCEPTED: the flags the fold added)
decided_by (composite FK -> app_users), decider_name, decided_at
release_audience_notes (written while APPROVED, immutable once PUBLISHED)
id (UUID PK); release_id + audience_id + language unique (V17)
(release_id, organization_id, project_id) FK -> releases, ON DELETE CASCADE
(audience_id, organization_id) FK -> audience_definitions (blocks deleting a used audience)
audience_code, audience_name, language, template_body_snapshot, footer_template_snapshot (V34)
content, auto_rerender, last_edited_by (composite FK -> app_users), last_editor_name
translation_status (READY | PENDING | FAILED, V17)
glossary_status (NONE | PENDING | APPLIED | NOT_APPLIED, V33), glossary_reason (exactly when NOT_APPLIED)
created_at, updated_at
release_notes (legacy, immutable; releases published before V13)
release_id (PK; composite FK with organization_id, project_id -> releases)
version, summary, sections (jsonb), markdown, published_at
automation_rules (V22, V23)
id (UUID PK), organization_id, project_id (null: every project)
name (unique per Organization ignoring case while active), enabled, active
trigger_type (RELEASE_PUBLISHED | MANUAL | SCHEDULED_CRON | UPCOMING_RELEASE_REMINDER
| EXTERNAL_WEBHOOK), with a CHECK per trigger for the columns it uses:
trigger_release_id, cron_expression, cron_time_zone (SCHEDULED_CRON)
reminder_days_before (UPCOMING_RELEASE_REMINDER)
webhook_id, webhook_secret_nonce + webhook_secret_ciphertext (EXTERNAL_WEBHOOK)
next_fire_at (null whenever the rule is disabled or archived)
created_at, updated_at
automation_rule_actions (V22)
id (UUID PK), rule_id, organization_id; rule_id + position unique (deferred)
action_type (GITHUB_RELEASE | SLACK | EMAIL | PUBLIC_CHANGELOG | NOTION | CONFLUENCE
| MICROSOFT_TEAMS | ZENDESK)
audience_id, target_language, configuration (jsonb object)
secret_nonce + secret_ciphertext (nullable, together)
automation_runs (V22)
id (UUID PK), rule_id, organization_id, project_id, release_id
rule_name_snapshot, release_version_snapshot, trigger_type
request_id (MANUAL and EXTERNAL_WEBHOOK), scheduled_for (cron and reminder)
initiated_by + initiator_name (MANUAL only)
status (PENDING | RUNNING | SUCCEEDED | FAILED | UNKNOWN | CANCELLED)
cancellation_requested, created_at, started_at, completed_at
automation_action_runs (V22)
id (UUID PK), run_id, organization_id, rule_action_id; run_id + position unique
action_type, audience_id, audience_name_snapshot, language_snapshot
note_content_snapshot, configuration_snapshot, secret_nonce_snapshot + secret_ciphertext_snapshot
status (as runs, plus SKIPPED since V39), external_reference
error_code (exactly when FAILED, UNKNOWN, or SKIPPED)
attempts, claimed_at, started_at, completed_at
automation_publish_jobs (V22, the publication outbox)
id (UUID PK), organization_id, project_id, release_id (unique)
status (PENDING | RUNNING | SUCCEEDED | FAILED), attempts, next_attempt_at, claimed_at
last_error, created_at, completed_at
public_changelog_entries (V24, immutable)
id (UUID PK), organization_id, project_id, release_id, action_run_id (unique)
organization_slug_snapshot, organization_name_snapshot, project_name_snapshot
release_version_snapshot, audience_name_snapshot, language, content_snapshot, published_at
organization_id + release_id + audience_name_snapshot + language unique
Authenticated ReleaseFlowPrincipal contains both user ID and Organization ID.
Request DTOs do not accept tenant identifiers. Tenant-owned repositories added
query using both the resource ID and the principal's Organization ID. Project
and integration queries apply that rule; a cross-tenant Project ID is reported
as not found. Composite foreign keys and uniqueness constraints provide the
database boundary. This decision is recorded in
ADR-0001.
Source connection credentials
A Project may have several integration sources: GitHub repositories, GitLab projects,
Linear teams, and Jira Cloud projects, each of which can be disconnected and reconnected
but never deleted (Source lifecycle and health). Owners, repository names, and GitLab project paths are
trimmed, lowercased, and validated before persistence; which fields a request
needs depends on its type, and IntegrationSourceRequestValidator reports the
missing ones against those fields so REST and Thymeleaf both show them. The same
canonical key may be connected by different Organizations, but only once inside
one Organization and per source type among connected sources
(integration_sources_external_unique, a partial unique index since V37), and is held
at most once by each Project (integration_sources_external_project_unique). V18 renamed github_integrations to
integration_sources in place, so every row kept its ID, webhook ID,
repository, and ciphertexts; V19 made the repository columns GitHub's alone and
added api_base_url and webhook_auth_mode. See
ADR-0016 and
ADR-0017.
A GitLab source also names its instance, the only provider address a request may
choose. GitLabBaseUrl accepts it only as a plain HTTP or HTTPS address — no
credentials, query, or fragment — whose origin is in
releaseflow.gitlab.allowed-hosts (gitlab.com by default), answering
400 gitlab_base_url_invalid or 400 gitlab_host_not_allowed otherwise. An
allowlist entry is host or host:port, which means HTTPS, or a full origin
such as http://gitlab.internal:8080. The allowlist is checked again before
every call, and GitLabApiClient never follows a redirect, so a redirect cannot
move a call to another host.
How a source is proven depends on its provider. For GitHub and GitLab, ReleaseFlow
creates a random UUID webhook identity and a 32-byte random signing secret. For Linear,
it creates the webhook identity, but the secret is the one Linear minted, pasted in when
the team is connected and never echoed. Jira has neither: it is polled, so its
webhook_auth_mode is NONE. A generated secret is returned only from the successful
creation response and is never exposed by Project reads. The UI renders the creation result directly with
Cache-Control: no-store rather than putting plaintext in a redirect or session
flash value.
At rest, AES-256-GCM stores a random 12-byte nonce and authenticated ciphertext.
Additional authenticated data binds the Organization, Project, and source, plus
the canonical repository for GitHub, or the source type and its external key (the
GitLab project path, the Linear team, or the Jira project key) for the others, to
prevent ciphertext relocation. GitHub's authenticated data has
never changed, so no ciphertext was ever rewritten. Every column the authenticated data
names is mapped updatable = false, so no lifecycle step can rewrite one. Startup requires a
Base64-encoded 32-byte key from RELEASEFLOW_CREDENTIAL_MASTER_KEY. Key and
credential material are never logged. See
ADR-0002.
An administrator may add or replace one access token per source.
IntegrationSourceService.replaceToken reads the source in one short
transaction, asks its provider outside any transaction — GitHub with
GitHubApiClient.checkPullRequestAccess
(GET /repos/{owner}/{repo}/pulls?state=closed&per_page=1), GitLab with
GitLabApiClient.checkProjectAccess (GET /api/v4/projects/{key} with
PRIVATE-TOKEN), Jira with JiraApiClient.checkProjectAccess, and Linear with
LinearApiClient.workspaceOf, which must still name the workspace recorded when the
team was connected — and stores the token in a second short transaction. Linear and
Jira are confirmed the same way when they are connected, because their token is
required from the start. The token uses the same cipher and authenticated data as the
secret plus a purpose line (github-access-token, gitlab-access-token,
linear-access-token, or jira-access-token), so a secret and a token can never be
swapped. Project reads report only whether a token exists
and when it was set. SourceAccess is the single way the change capability
obtains a source's coordinates and decrypted token, always by Organization,
Project, and source ID; it answers for connected sources only. Saving a token marks the
source ACTIVE again, and a Jira token may come with a new accountEmail, confirmed by the
same call and written to credential_identity, which no ciphertext is bound to. See
ADR-0008.
Source lifecycle and health
ADR-0042. A change is identified by
(source_id, external_id), and changes_source_type_matches points every change at its
source, so a source row is never deleted and a reconnect reuses it.
- Disconnect.
IntegrationSourceService.disconnectnullswebhook_id, the secret, the token, andnext_poll_at, setsdisconnected_atanddisconnected_by, and publishesSourceDisconnectedinside the same transaction.SourceDisconnectionListenerin thechangecapability fails the source'sPENDINGorRETRY_SCHEDULEDsync job assource_disconnected;SourceSyncWorkerreads the credentials again before every page, so a running job stops at the next one.IntegrationSource.recordPoll,recordPollFailure, andrecordSyncdo nothing for a disconnected source, so a job finishing late books nothing. With nowebhook_id, a verifier finds no source and the path answers like an unknown one.SourceAccess.find,findByType,findSole, andfindDuePollsskip disconnected sources, so a change still processing completes asNO_ACCESS_TOKEN, linked context and issue reads see no tracker, andReleaseLinkBuilderandNextStepcount connected code hosts and sources only. - Reconnect.
reconnectreads the source in one short transaction, checks no other Project connected the key since, asks the provider outside any transaction when there is a token (Linear'sworkspaceOfmust still answer the stored workspace), and writes in a second: a newwebhook_idand secret under the same authenticated data, or for Jira a cursor of no earlier than 90 days ago and the next poll one interval later.createrefuses a key its Project holds disconnected with409 source_reconnect_required. - Rotation.
generateSecret(GitHub, GitLab) andreplaceSecret(Linear, or awhsec_token GitLab generated for a signed source) replace the ciphertext under the same authenticated data, setsecret_updated_at, and reset the failure count. No provider is called, and the old secret stops at once. - Signature failures. Each verifier resolves the source first and, when the proof
fails, hands it to
SignatureFailureRecorder, which writes the first failure on a source at once and adds later ones within a second to an in-memory count, drained once a second (and on shutdown) by oneUPDATEper source. TheUPDATEadds to the stored count and applies only whilesecret_updated_atis the one the failures were refused under. The entity maps the two columns as not insertable or updatable, so an ordinary flush can never overwrite a concurrent increment. - Health.
SourceViewsbuilds everyIntegrationSourceViewwith aSourceHealth. One native query per list computes, for each connected delivered source, the gaps between itsWEBHOOKchanges of the last 90 days and their 90th percentile (changes_source_delivered_idx); with at least ten gaps, the usual gap is that percentile or an hour, whichever is longer, and the source is quiet when its last delivery, or its secret's last setting, is older. A connected Jira source is overdue when its next poll is more than one interval past. Nothing is scheduled or stored for it. - Pages.
SourcePageControllerserves/projects/{projectId}/sources/{sourceId}, its disconnect confirmation, the shown-once secret page, and the reconnect result. The confirmation names the enabled rulesSourceTokenBorrowersreports — theprojectport thatAutomationRuleServiceimplements, soprojectnever reaches intoautomation.fragments/source-healthdraws the same health in the Change Inbox, the overview, the Projects page, and the source page.
Source intake
The three provider webhooks share the /webhooks/** filter chain described under
Security: it permits exactly the signed endpoints, excuses only them from
CSRF, creates no session, and saves no request. Each provider's own verifier
establishes trust instead. A delivery larger than releaseflow.webhooks.max-body-bytes (1 MiB) is
refused with 413 webhook_payload_too_large before any source is looked up, so
the limit reveals nothing about which sources exist.
GitHub
For GitHub, trust comes only from the signature, verified in this order:
GitHubWebhookVerifierin theprojectcapability looks the integration up by the untrusted webhook ID. This is the one lookup without an Organization ID, as anticipated by ADR-0002.- It decrypts that integration's secret with its tenant-bound authenticated
data, computes HMAC-SHA256 over the raw request bytes, and compares it with
X-Hub-Signature-256in constant time. An unknown or malformed webhook ID, a missing or malformed header, a wrong signature, and an undecryptable secret all produce the same401 webhook_signature_invalidresponse. - Only then does
GitHubWebhookServicein thechangecapability parse the JSON. The Organization and Project come from the verified source; any tenant field in the payload is ignored. Arepository.full_namethat does not match the configured repository case-insensitively, or a pull request without one, is rejected with422 webhook_repository_mismatch.
ping is acknowledged. A pull_request delivery with action closed and
merged: true is normalized into a changes row; other events and actions are
acknowledged and ignored. Signed but malformed deliveries receive
400 webhook_payload_malformed, and nothing is written for any rejected
delivery.
Idempotency relies on the changes_source_external_unique constraint on
(source_id, external_id), the pull request number within its source.
ChangeIntake, shared by webhook deliveries and history imports, checks for an
existing row first and treats a concurrent unique violation as a duplicate, so
redeliveries return 200 duplicate. The first
delivery ID is retained on the row. Every accepted delivery advances the
integration's last_delivery_at, which the Projects page shows as setup step
three. Intake stays short: one transaction inserts the change, PROCESSING,
Unknown, and in review, together with a PENDING row in
change_processing_jobs. The webhook request makes no GitHub call.
GitLab
POST /webhooks/gitlab/{webhookId} works the same way, with the check the
source was set up for. GitLabWebhookVerifier resolves the source by the
untrusted webhook ID, requires it to be a GitLab source, and decrypts its secret
with that source's authenticated data. Then, in GITLAB_SIGNING_TOKEN mode, it
requires webhook-id, webhook-timestamp, and webhook-signature, a timestamp
within releaseflow.gitlab.webhook-clock-skew (five minutes) of the clock, and
a signature of id.timestamp.body under the Base64-decoded secret, written as
v1, and Base64; the header may hold several space-separated candidates, every
one of which is compared. In GITLAB_SECRET_TOKEN mode it compares
X-Gitlab-Token with the secret in constant time. WebhookSignatures holds the
arithmetic both providers share. Every failure answers the same
401 webhook_signature_invalid.
GitLabWebhookService then parses the JSON. An event that is not
object_kind: merge_request is acknowledged and ignored without reading further.
A project.path_with_namespace that is not the connected project is rejected
with 422 webhook_repository_mismatch, and only object_attributes.action: merge is recorded. MergedMergeRequest normalizes the delivery into the same
MergedPullRequest a GitHub pull request becomes: iid is the number, the
merge commit falls back to the squash commit and then to the last commit, and
the merge time falls back to the last update, which older GitLab instances write
as 2026-09-10 09:14:22 UTC.
GitLab identifies a delivery only in its signing mode, and not always with a
GUID, so a change records X-Gitlab-Event-UUID when it parses as a UUID and
nothing otherwise. changes_import_has_no_delivery therefore only requires that
an imported change has no delivery ID, while GitHubWebhookService still
demands X-GitHub-Delivery.
Linear
POST /webhooks/linear/{webhookId} is the third provider path on the same filter chain.
LinearWebhookVerifier resolves the source by the untrusted webhook ID, requires
it to be a Linear source, decrypts its secret, and then requires all four of, in this
order: a Linear-Delivery header (and a Linear-Signature one); a hex HMAC-SHA256 of
the raw bytes equal to Linear-Signature, compared in constant time; a
webhookTimestamp, the time Linear sent the delivery, within
releaseflow.linear.webhook-clock-skew (60 seconds) of the clock, read as
milliseconds when the number exceeds 1e10, as epoch seconds below that, or as
ISO-8601; and an organizationId equal to the workspace recorded when the team was
connected. createdAt, the time of the issue's change, is not a proof
(ADR-0018, amended 2026-11-19). Unlike the other two
verifiers this one parses the body, because Linear puts the timestamp and the workspace
inside it rather than in headers; an unreadable body is one more way to fail, and every
failure answers the same 401 webhook_signature_invalid. A refusal on a known path is
logged by LinearRefusalLog with the source's ID and the proof that failed, a stale
stamp with its offset in seconds, and never the body, a header's value, the secret, or
the caller. It writes at most one line per source and reason a minute: refusals in
between are counted in a ConcurrentHashMap keyed by source and reason, the next line
says how many were left out, and a sweep every ten seconds writes a count whose minute
is over and forgets entries with nothing left to say, so the map holds only what was
refused in the last two minutes.
LinearWebhookService then decides whether the delivery is a change at all.
CompletedIssue.isCompletion requires type Issue, action update, an
updatedFrom carrying stateId, stateType, or state, a new state type of
completed, and an old one that is not — a real transition into done, not an
edit to something already done. Anything else is acknowledged and ignored. The
issue's team, data.team.id or data.teamId, must be the connected team, or the
delivery is 422 webhook_repository_mismatch.
CompletedIssue.fromWebhook normalizes the issue into the same
MergedPullRequest: data.number is the number a person sees, data.id is what
the source names it by and what makes it idempotent, and the merge commit and
target branch are null. Linear identifies no delivery ReleaseFlow could record as
a GUID, so a Linear change has no delivery ID.
Jira polling
Jira is the one source nobody delivers to (ADR-0019). Connecting it asks
GET /rest/api/3/project/{key} with Basic email:token credentials, then stores
the site, key, account, and encrypted token with no webhook identity, a
poll_cursor_at of now, and a next_poll_at one
releaseflow.jira.poll-interval (five minutes) later.
- Scheduling. Every tick,
SourceSyncWorkerfirst callsJiraPollScheduler.scheduleDuePolls(now). For each Jira source whosenext_poll_athas passed and which has noPENDING,RUNNING, orRETRY_SCHEDULEDjob, it inserts aJIRA_POLLrow insource_sync_jobswith no requester, an unlimited item limit, and the window[poll_cursor_at − releaseflow.jira.poll-overlap, now]. The one-active-job index still decides a race between two workers. - Reading.
JiraPollReaderasksGET /rest/api/3/search/jqlforproject = "KEY" AND statusCategory = Done AND updated >= "…" ORDER BY updated ASC, 100 at a time, followingnextPageToken. The token is the provider half of the job'sSyncCursor. Each issue is judged on itsresolutiondate(elseupdated) and goes through the sameChangeIntake.record(..., IMPORT)as an import, so an issue seen by two overlapping polls is recorded once. - Bookkeeping. A completed poll calls
IntegrationSourceService.recordPoll, which movespoll_cursor_atto the window's end, setsnext_poll_atone interval later, and marks the sourceACTIVE. A poll that must wait keeps its cursor and marks the sourceERROR; one that fails for good does the same and setsnext_poll_at15 minutes later, so the schedule resumes on its own. The source recordsjira_unavailablewhen Jira could not be reached. - Addresses.
JiraSiteUrlaccepts only an HTTPSatlassian.nethost with no port, credentials, query, or fragment, andJiraApiClientchecks it again before every call and never follows a redirect.releaseflow.jira.api-base-url, empty by default, is a deployment-only override that sends every call to one fixed address for tests and local runs.
Background work
Every call to another system that a request does not wait for runs in one of seven
scheduled workers. Each claims its work with FOR UPDATE SKIP LOCKED in a short
transaction, calls out with no transaction open, and records the result in another
short transaction that first checks the claim is still its own. Retries are bounded.
| Worker | Every | Table | Work |
|---|---|---|---|
ChangeProcessingWorker | second | change_processing_jobs | Enrich and classify a change |
SourceSyncWorker | second | source_sync_jobs | History imports, and Jira polls that JiraPollScheduler books |
TranslationWorker | second | translation_jobs | DeepL translations of change summaries and release summaries |
LinkedIssueReadWorker | 2 seconds | linked_issue_reads | Read a release's linked issues again when its review is requested |
GlossarySyncWorker | second | glossary_syncs | Send a language pair's glossary dictionary to DeepL, one sync per Organization at a time |
AutomationWorker | second | automation_publish_jobs, automation_action_runs | Turn publications into runs, then deliver one action at a time |
AutomationTriggerWorker | RELEASEFLOW_AUTOMATION_TRIGGER_DELAY (15 s) | automation_rules, automation_runs | Book runs for due schedules and reminders; it never calls a provider |
Change processing
ChangeProcessingWorker runs every second on the scheduler and drains due
jobs. Each step is its own short transaction, and the provider and AI calls
happen between them:
- Jobs left
ENRICHINGfor more than ten minutes return toPENDING; jobs leftCLASSIFYINGbecomeFALLBACK_REQUIRED. - One due
PENDINGorFALLBACK_REQUIREDjob is locked withFOR UPDATE SKIP LOCKED. AFALLBACK_REQUIREDjob is completed at once from the recorded files, with the rules and aCLASSIFIER_FALLBACKtrigger, never asking the AI again. APENDINGjob is markedENRICHING, its attempt counted, and its claim time recorded, so several workers never take the same job. - Without a transaction,
SourceAccesssupplies the coordinates and token of the change's source, and theSourceEnricherof its type asks the provider for everything it can add. GitHub lists a pull request's files, 100 per page for at most five pages; GitLab lists a merge request's diffs for at most ten; Linear lists nothing, because an issue has no files, and instead reads the issue back over GraphQL so the change carries its current wording; Jira lists nothing and restates nothing, because the poll read the issue moments earlier.LinkedContextEnricherthen asks the Project's Jira source what the change mentions (see Linked context). A full last page, a refused or missing token, or an invalid response is final, and so is a diff GitLab reports as collapsed, too large, or truncated, which makes the whole list unavailable rather than short. Timeouts, network errors, rate limits, an issue Linear will not confirm, and 5xx responses are retried after 2 and 4 seconds, up to three attempts. - The rules classify the change — as the provider restated it — with the result. Without an AI provider, the
change and job are completed together. With one, the files are recorded on
the change and the job becomes
CLASSIFYING; then, with no transaction open, the AI is asked once in the Organization's output language; finallyChangeAiMergecombines the answer (or failure) with the rules and the change and job are completed. Every write checks that the job still carries this worker's claim, so a claim that went stale and was taken over is discarded.
A linked-context lookup that is PARTIAL or UNAVAILABLE is retried on the
same three attempts as the source's own enrichment.
An unexpected failure while collecting files reschedules the job rather than
skipping it, so the change stays visibly Processing. Once the job is
CLASSIFYING it is never rescheduled; if it stalls, the stale recovery
completes it without AI. Changes recorded before Flyway V10 were
marked COMPLETED and are never processed.
The database protects the outcome. changes_processing_unsettled keeps a
PROCESSING change Unknown, in review, unreviewed, without triggers, an AI
result, or a summary (it may carry its recorded files), so it cannot be
released, reviewed, or sent to AI. The service layer
also rejects such a review with 409 change_processing.
changes_triggers_require_review allows review triggers only on changes that
need or have received review.
Linked context
A GitHub or GitLab change may mention issues of the Project's Jira project or Linear team
(ADR-0019, ADR-0041). LinkedContextEnricher runs after the source's own enricher,
outside any transaction:
- A change from Linear or Jira is
NOT_SUPPORTED. A Project with neither a Jira nor a Linear source that has a token, or a change whose own source has no token, isNOT_CONFIGURED. Each tracker is found by type withSourceAccess.findByType, the oldest first. SourceEnricher.commitMessageslists at most 250 commit messages over three pages (GET /repos/{o}/{r}/pulls/{n}/commitsorGET /api/v4/projects/{key}/merge_requests/{iid}/commits). They are evidence only: never stored, never sent to the AI.IssueKeys.extractfinds one tracker's keys, case-insensitive, uppercased, deduplicated in first-seen order, at most ten, as(?<![A-Za-z0-9_])(KEY-[1-9][0-9]*)followed by what the place allows:- title and target branch:
(?![A-Za-z0-9_-]), so a key followed by a hyphen names nothing; - head branch (
changes.head_branch, V31):(?![A-Za-z0-9]), so-,/,_, or the end of the name follows; - description and commits: the strict rule, or
-and a lowercase letter (Spec: DBV-12-quartz). Only a tracker's own key is ever searched for, so another prefix (ISO-8601-compliant) never links.
- title and target branch:
- A Jira key is read with
GET /rest/api/3/issue/{key}?fields=summary,description,issuetype,status. The description is Atlassian Document Format flattened to plain text and capped atreleaseflow.jira.description-max-characters; the status category isfields.status.statusCategory.key. - A Linear identifier is read with one GraphQL
issue(id:)query and kept only when the issue's team and workspace are the source's; its state typecompletedorcanceledis the categorydone. The team key isintegration_sources.external_team_key; a source without one asks for it once (team(id:){key}) and keeps it throughSourceAccess.rememberTeamKey, and a key it cannot read makes the changeUNAVAILABLE.
No key and readable commits is NOT_FOUND; unreadable commits are PARTIAL; a
key a tracker would not show, or a team key that could not be read, is UNAVAILABLE;
otherwise COLLECTED. Each LinkedIssue records its tracker and statusCategory
(open or done); an issue recorded before V35 has neither, reads as Jira, and its
category is unknown. The worker
records the status and issues beside the changed files, ChangeClassifier adds
LINKED_CONTEXT_UNAVAILABLE for PARTIAL and UNAVAILABLE, the AI prompt gets
a top-level linked_issues array, the Change Inbox lists the issues, and audience
templates may print them through {{#linkedIssues}}.
History import
ADR-0016 imports a source's merged pull and merge requests of the last 90 days, and ADR-0017 gives each provider its own reader.
- Jobs.
SourceImportServicequeues aHISTORICAL_IMPORTrow insource_sync_jobsfor a source with a token, with its window, cursor:0(the first page), andreleaseflow.import.item-limit(500). The partial unique indexsource_sync_jobs_one_activeallows onePENDING,RUNNING, orRETRY_SCHEDULEDjob per source; a second request returns409 source_sync_in_progress. Resuming aPARTIALorFAILEDjob puts it back toPENDINGwith its cursor, a zero imported count, and zero attempts. - Readers. A
SourceHistoryReaderper source type turns one page into normalized items, andSourceHistoryReadersfails at startup if a type that has a history lacks one.SourceType.supportsHistoryImport()says which types those are; Linear and Jira are not, soSourceImportServiceanswers409 source_import_not_supportedand the Change Inbox does not list it.GitHubHistoryReaderasksGET /repos/{owner}/{repo}/pulls?state=closed&sort=updated&direction=desc&per_page=100&page=N, newest update first, so an item updated before the window means there is nothing older left and it ends the scan.GitLabHistoryReaderasksGET /api/v4/projects/{key}/merge_requests?state=merged&order_by=updated_at&sort=asc&per_page=100&page=N&updated_after=…, so the list only grows at its end and an older item never appears. - Worker.
SourceSyncWorkerruns every second (off in tests, like the change worker). It releasesRUNNINGjobs claimed more than ten minutes ago, claims one due job withFOR UPDATE SKIP LOCKED, and then, outside any transaction, reads pages through that reader. From the cursor's offset, each item is counted as scanned; one merged inside the window goes throughChangeIntake.record(..., IMPORT), which creates the change and its processing job or reports a duplicate. At the item limit the job becomesPARTIALwith the cursor on the next item, and a page the provider says is its last completes it. The cursor and counts are saved in a short transaction after every page. - Failures. A 429, or a 403 with
Retry-Afteror an exhausted rate limit, waitsmin(Retry-After or the reset time, one hour); a 5xx or network failure waitsmin(300, 2^attempt)seconds; the fifth attempt fails. 401, 404, and other 403 responses fail at once and mark the sourceERRORthroughIntegrationSourceService.recordSync, which also recordslast_sync_atand the error code,github_unavailableorgitlab_unavailablenaming the provider that could not be reached. An unreadable item is skipped with a warning. - Changes. Imported changes have
origin = IMPORTand nodelivery_id, whichchanges_import_has_no_deliveryenforces. The Change Inbox shows each source's latest import with Import and Resume actions for administrators, and an Imported badge on the cards.
Because GitHub orders the list by update time, a pull request updated while an import is running can move between pages and be skipped or seen twice. Seeing it twice is harmless, and webhooks cover anything merged after connection. A GitLab import asks for the same window every time, so a merge request updated during the run moves to the end of the list rather than past the cursor.
Deterministic classification
ChangeClassifier runs in the worker once the provider has been asked. It uses
the change's title, labels, description, and file list, and never performs
network I/O itself.
| Signal | Rule | Effect |
|---|---|---|
| Title type | ^(feat|fix|perf|docs|refactor|chore|ci|build|test)(scope)?(!)?: text, case-insensitive | Feature, Fix, Performance, Documentation, or Maintenance group |
Title ! | Marker after the type or scope | Breaking |
| Label | enhancement, feature; bug, bugfix; performance; documentation, docs; dependencies, maintenance, chore, refactor | Category, only without a title type |
| Breaking label | breaking-change, breaking change, breaking | Breaking |
| Footer | A description line starting with BREAKING CHANGE: or BREAKING-CHANGE: | Breaking |
| Files | Every changed file is in docs/ or ends in .md, .adoc, or .rst | Documentation, before the title type |
| Sensitive path | A changed or previous path matches releaseflow.classification.sensitive-paths or one of the Project's additions | SENSITIVE_PATH review trigger |
| No file list | The files could not be listed | CHANGED_FILES_UNAVAILABLE review trigger |
| Sensitive word | The source has no files at all, and the title or description contains breaking change, migration, security, auth, credential, password, or encryption | One SENSITIVE_KEYWORD review trigger per match |
| Linked issues | Commits could not be read, or Jira would not show a mentioned issue | LINKED_CONTEXT_UNAVAILABLE review trigger |
| Migration kind | The AI's migration kind did not match its step, and the parser corrected it | MIGRATION_KIND_MISMATCH review trigger, added by ChangeAiMerge |
A source that cannot report files at all is not a source whose files failed to
arrive. ChangedFileStatus.NOT_SUPPORTED says so, and the keyword scan stands in
for the path rules: it reads only the title and description, because that is all
such a source gives, which is exactly why it is never used for a source that can
do better. A change from such a source needs review only when a word matches.
Each category rule names a group and a preferred code (the former fixed value,
such as FIX). The Organization's active catalog, passed in by the caller,
decides the category: the preferred one if active, else the first active
category of the group by code. A group without an active category locks nothing
and adds the reason "No active category in the … group". A title type outranks
labels, and every matched rule is kept as a reason, so a disagreement stays
visible. Labels naming different categories without a title
type, or no matching rule at all, produce Unknown. needs_review is true for
every breaking, Unknown, or triggered change; the changes_review_required
and changes_triggers_require_review check constraints enforce that invariant
in the database as well. Review triggers are stored as typed JSON
({type, detail}) beside the textual reasons. SensitivePathRules compiles
the configured JDK globs at startup, also matching **/x patterns at the
root, and refuses to start with an invalid pattern or an empty list. Flyway V4
assigns Unknown, needs review, and the reason "Recorded before rule-based
classification" to changes recorded before it ran.
Sensitive paths per Project
ADR-0014 lets administrators add patterns for one Project. The baseline stays
in SensitivePathRules; ProjectSensitivePathService stores a Project's
additions in project_sensitive_paths (Flyway V16: one row per Project with
the patterns as a JSON array of at most 100, composite foreign keys to the
Project and to the administrator who last changed them). The worker, a job
completed without AI, and an AI retry all ask the service for the Project's
SensitivePaths, the baseline followed by the additions, so the baseline can
never be removed, and changes classified earlier keep their triggers.
SensitivePathAdditions trims the patterns, drops blank lines and repeats,
and rejects more than 100, any longer than 256 characters, or one that does not
compile, with 400 invalid_sensitive_paths. Everything lives in the change
package, which already depends on project, so the page is its own
/projects/{projectId}/sensitive-paths rather than part of the Projects page.
Members may read it and GET /api/projects/{projectId}/sensitive-paths;
SecurityConfiguration limits the PUT and the page's POST to
administrators. See ADR-0014.
Change Inbox
ChangeInboxService serves both GET /changes and
GET /api/projects/{projectId}/changes. It first resolves the Project through
ProjectService.get with the principal's Organization ID, so another tenant's
Project is reported as not found. It then queries changes by both Organization
and Project ID, optionally filtered by category code, review status, and
insufficient context, newest merge first. Cards show each change's category snapshot, a pending category
proposal, and, for administrators, the forms that decide it. Unsupported filter values return 400 invalid_change_filter. The
page opens on the Project named in the URL, else the remembered one (see
Workspace overview), else the first, and uses a plain GET form
for filters.
AI classification
AI is optional. AiClassifierConfiguration builds exactly one
AiChangeClassifier from RELEASEFLOW_AI_PROVIDER, or none:
OpenAiCompatibleClassifierservesopenai(Chat Completions with a strict JSON Schema andstore: false) anddeepseek(the same API withjson_objectand the schema in the prompt), throughRestClient;AnthropicChangeClassifierservesanthropicthrough the official Java SDK, with Structured Outputs (output_config.format) and SDK retries disabled.
All three share AiClassificationPrompt (instructions, response schema, and
the user JSON) and AiClassificationParser, which rejects an incomplete or
mistyped answer as a whole. The request names the Organization's audiences
(code and communication intent, from AudienceService.briefs), and the
response schema is built for each request with one required narrative object
per audience code (relevance of none, brief, or full, a headline, and a
body; ADR-0035), which OpenAI strict mode and Anthropic Structured Outputs
enforce. The parser reads only the requested codes; a missing or mistyped
narrative is left out without failing the answer, an unknown relevance reads as
full, a headline over 20 words or several lines is dropped, Limitations
drops a headline, or a sentence of a body, that remarks on the input, and a
plain string is a full body. A narrative that says no more than having none
(AudienceNarrative.saysNothing: full, with neither headline nor body) is left out. Every provider refuses to run inside a transaction
and turns timeouts, HTTP errors, refusals, truncation, and invalid JSON into a
fixed message that never contains a key or a response body. See
ADR-0009, which supersedes
ADR-0004.
ADR-0035 binds the answer to its evidence. The user JSON names the item change,
with kind set to tracker_issue when its source is Linear or Jira
(SourceType.isIssueTracker) and code_change otherwise, and carries the
Project's context as project_context, or null. The worker and a retry read
it through ProjectService.context before the call, outside any transaction.
The instructions forbid, in every field, consequences, product locations, and
tracker-issue files the evidence does not state, a dependency's quoted
changelog presented as this project's change, and remarks about missing
evidence. neutral_core gains migration_kind and limitations. The parser
never rejects an answer over the kind: none with a step becomes recommended,
any other kind (or none at all) without a step becomes none, a step with an
unknown kind becomes recommended and one with no kind unspecified, and the answer records what the AI returned
so ChangeAiMerge adds a MIGRATION_KIND_MISMATCH trigger. Before the kind is read,
MigrationSteps.stated empties a step that only says nothing needs doing ("No
immediate action is required", "No migration required") unless the verdict is
qualified or another clause still asks something, so its kind becomes none. A missing
limitations reads as empty, and Limitations.stated drops every sentence of it that
talks about the input ("not provided", "not specified", "no information", and their kin
in English and Vietnamese) or only states the change's scope ("does not affect", "has
no impact on", "only affects") rather than what the change does not do yet. Both read
only the answer, so the request, and replays recorded from it, are unchanged. NeutralSummary stores both;
a summary stored before them reads its step as UNSPECIFIED (MigrationKind),
which no template or label treats as required.
A dependency update is recognized by DependencyUpdates from the author
(dependabot[bot], renovate[bot]) or the head branch (dependabot/, renovate/),
which MergedPullRequest reads from GitHub's head.ref and GitLab's source_branch, in
deliveries and imports alike, and changes.head_branch keeps (Flyway V31; only a code
host's change has one). AiClassificationRequest.of sends such a change's description
without its <details> and <blockquote> elements, Markdown blockquotes, and "Release
notes", "Changelog", and "Commits" sections, and marks it dependency_update; the stored
description is untouched. AiClassificationPrompt.system adds DEPENDENCY_RULE (breaking,
or a migration step, only when the change's own words say so) to the instructions only for
such a change, after the first rule: when unsure whether a change is breaking, set
breaking_change and needs_human_review. AiClassifierConfiguration.temperature reads
RELEASEFLOW_AI_TEMPERATURE at startup: AiClassificationPrompt.TEMPERATURE (0) when it
is empty, a number within AiProvider.maxTemperature(), or none for default, which leaves
the field out of the request for a model that accepts only its own (ADR-0038). Without a
provider the value is not read; with one, a value that is not default or a number in the
range stops startup. OpenAiCompatibleClassifier sends it. A 400 whose error.param is
temperature sends the same request once more without it and sets the client's
temperatureRefused flag, so every later request of the process leaves it out; the first
thread to set it logs one warning. The error body is read only to decide this. Any other
failure, the second request's included, becomes the change's failure as before (ADR-0039).
AnthropicChangeClassifier takes no temperature: anthropic-java 3.x sends API version
2026-10-21, which refuses temperature, top_p, and top_k, and the API key as
Authorization: Bearer. ReleaseFlow sets no version of its own. The configuration only logs,
once at startup, that a number other than 0 is ignored, and every Anthropic failure is the
change's, with no second request (ADR-0045).
Project context
projects.context (Flyway V30, at most 2000 characters, with who changed it
last and when) is written by administrators through
PUT /api/projects/{projectId}/context and the page
/projects/{projectId}/context, both limited to administrators by URL rule in
SecurityConfiguration; members read it with GET. ProjectService owns it, so
change and translation read it through ProjectService.context with the
principal's or the job's Organization ID. Nothing is classified again when it
changes.
The change worker calls the AI automatically (see Change processing).
ChangeAiMerge combines the rules with the answer:
- the rules' category is kept unless it is Unknown;
breakingis the rules' flag OR the AI's;needs_reviewis set when the change is breaking, Unknown, has any review trigger, or the AI asked for review;- otherwise the AI's answer settles the change, and the source is
AIonly when the AI chose the category.
A failure keeps the rule result and adds a CLASSIFIER_FALLBACK trigger. The
change stores neutral_summary (JSONB), audience_narratives (JSONB),
content_language, ai_provider, and ai_model. A summary that a person
wrote through ChangeSummaryService records its writer and is never replaced
by a later AI answer. changes_neutral_summary_consistent,
changes_ai_provider_recorded, and changes_ai_state_consistent keep them
coherent.
ChangeAiClassificationService lets a person retry. It is limited to a
completed, unreviewed change whose AI attempt failed, or an Unknown change
recorded before automatic AI. Like the worker, it reads in one short
transaction, calls the provider with none open, and records the result in a
second transaction only if the change is still eligible. Existing triggers are
kept, so a change that needed review still does. The REST endpoint reports a
stored failure as 502 ai_classification_failed.
Output language
organizations.output_language holds a canonical BCP 47 tag.
OutputLanguage.parse accepts any tag whose primary language is an ISO 639
code, turns _ into -, and limits the result to 16 characters.
OutputLanguageService serves registration, the Projects page form, and
GET|PUT /api/organization/output-language. Changing the tag is
administrator-only by URL rule. The worker reads the tag once per change and
records it as the summary's content_language.
Review signals
Two signals add review triggers after classification; they never settle,
merge, or remove a change. See
ADR-0013.
ClassificationSettings reads and validates their thresholds at startup
(releaseflow.classification.context-threshold, default 60;
releaseflow.classification.duplicate-threshold, default 0.82).
- Context sufficiency.
- The AI request carries
context_threshold, and the schema requirescontext_sufficiencywith a score and reasons. The parser rounds and clamps the score and keeps at most five reasons. ContextSufficiency.assesslowers the score with the fixed caps for an empty description (30), a short title (50), and a generic title (40), and merges their reason codes after the AI's.ChangeAiMergeassesses only a successful answer and adds oneCONTEXT_INSUFFICIENTtrigger below the threshold.changes_context_consistentkeeps the three context columns together, in range, and present only with a successful AI attempt.
- The AI request carries
- Possible duplicates.
DuplicateDetectorruns in the worker's completing transaction, also when a stalled classification is finished without AI. It reads at most 500 other processed changes of the Project received in the last 180 days by the application clock.DuplicateSimilaritycompares title and content trigrams after NFKC, lower-casing, and collapsing other characters, and the changed and previous file paths when both sides list files.- Pairs at or above the threshold become
duplicate_candidatesrows (at most five, most similar first) andDUPLICATE_CANDIDATEtriggers on the new change throughChange.addReviewTriggers, which only adds. DuplicateCandidateServicelists pairs with both sides for the Inbox and REST, and records one decision per pair; a second decision is409 duplicate_candidate_decided.
Category catalog
category owns the catalog and the proposals; it depends on neither change
nor release. See ADR-0012.
CategoryServiceserves the pages and REST (writes are administrator only by URL rule), the rules and the AI (active), and reviews (find, active codes only, ignoring case).CategoryRefis the snapshot a change stores: code, display name, and group.CategoryRef.normalizeupper-cases a code, turns-and spaces into_, and rejects anything but[A-Z][A-Z0-9_]*of at most 64 characters.- A system category (only UNKNOWN) keeps its group and cannot be archived
(
409 category_system). Archiving is reversible and never touches changes. - The AI request lists the active categories, and the schema's
categoryenum is their codes.suggested_categoryis always an object whose empty code means no proposal, which keeps OpenAI strict mode and Anthropic Structured Outputs simple. AiClassificationParserrejects a code outside the catalog as invalid. It keeps a proposal only with an Unknown answer, a valid code not already listed, and no rules lock.ChangeAiMergethen adds aCATEGORY_SUGGESTION_PENDINGtrigger, and the worker, or the AI retry, stores the proposal throughCategorySuggestionService.proposein the transaction that records the result.CategorySuggestionService.decidechecks that the proposal is still pending before doing anything.- APPROVED activates the proposed category, creating it or restoring an archived one with that code; MAPPED needs an active category; REJECTED adds nothing.
- It then publishes
CategorySuggestionDecided. CategorySuggestionDecisionListenerinchangegives the category to the change if it is still Unknown and unreviewed, with the sourceSUGGESTION.needs_reviewand the trigger stay until a person reviews the change.
Flyway V14 enforces the catalog with these constraints:
category_definitions_code_valid,category_definitions_group_known,category_definitions_system_active, andcategory_definitions_unknown_is_systemkeep the catalog valid;changes_category_validkeeps the snapshot valid, UNKNOWN always in the OTHER group;changes_ai_state_consistentrequires a successful AI attempt for theSUGGESTIONsource;category_suggestions_decision_recordedkeeps each suggestion's decision consistent.
Human review
ChangeReviewService settles one change in a single transaction. It loads the
change by ID, Organization ID, and Project ID, and requires a concrete
category. It then stores the category, breaking flag, and security flag exactly as
the reviewer submitted them, sets needs_review = false, and records
reviewed_by, reviewer_name, and reviewed_at. Because the reviewer
submits explicit values rather than approving whatever is current, a stale
page cannot confirm a classification it did not show. Any change may be
reviewed, including one already settled by rules or by an earlier review; the
latest review is kept.
Confirming unchanged values keeps the classification source (RULES or AI).
Changing any value sets it to HUMAN. A reviewer may clear a breaking or security
flag: the invariant that they require human review is met by the recorded review
itself. ChangeReviewRequest.security is optional, for callers written before ADR-0037:
null confirms the flag the change has.
Flyway V6 adds a unique (id, organization_id) key on app_users so that
changes_reviewer_fk keeps reviewers inside the change's Organization. It
redefines the review constraints so that breaking, Unknown, and AI-suggested
changes can leave review only with a recorded review, a HUMAN source always
has one, and a reviewed change is never Unknown. A reviewed change is no longer
Unknown, so it is never eligible for AI classification. The inbox status
filter distinguishes needs-review, classified (settled without a person),
and reviewed.
Excluding a change from releases
ChangeExclusionService records an administrator's decision that a change never
ships, on the change itself (excluded_by, excluder_name, excluded_at,
exclusion_reason, V29), and takes it back by clearing them; see
ADR-0033. It locks the change row
(PESSIMISTIC_WRITE), refuses a processing change, an excluded one, and one that any
release_changes row holds, and never touches the classification or the review.
ChangeInboxService.releasableChanges leaves excluded changes out, so neither the
available list nor Add all available offers them, ReleaseService.addChanges
refuses one named explicitly with 409 change_excluded, and the overview's
needs-review count skips them. The release_changes_change_not_excluded trigger reads
the change FOR SHARE before an insert: an exclusion that holds the row is waited for
and then seen, and an insert that holds it makes the exclusion wait and then find the
release.
Release lifecycle
The release capability reads changes only through the public
ChangeInboxService.releasableChanges and ChangeInboxService.changes
methods, both scoped by Organization and Project, and records reviews through
the public ChangeReviewService.review, and records summaries through the
public ChangeSummaryService.edit. change does not depend on release;
both depend on audience. ReleaseService looks a Project up through
ProjectService.get and a release by ID, Organization ID, and Project ID.
A release moves DRAFT -> IN_REVIEW -> APPROVED -> PUBLISHED; see
ADR-0010. Release owns the status
checks and the service checks the release's changes and decisions.
| Operation | Allowed in | Also requires |
|---|---|---|
| Edit version or summary, add changes | DRAFT | a processed change that is in no other release |
| Remove a change (reject during review) | DRAFT, IN_REVIEW | |
| Request review | DRAFT | at least one change; queues a read of its linked issues |
| Accept a linked issue's status, decide a folding suggestion | IN_REVIEW (an acceptance also APPROVED) | an issue or suggestion of this release |
| Record a decision | IN_REVIEW | a change of this release |
| Approve (writes the audience notes) | IN_REVIEW | a decision on every change |
| Edit a change's summary | IN_REVIEW, APPROVED | a change of this release |
| Edit an audience note | APPROVED | a note of this release |
| Return to draft | IN_REVIEW, APPROVED | |
| Schedule, discard | any status before PUBLISHED | a future time, or none |
| Publish | APPROVED | its audience notes |
A Project may prepare several releases at once. Any change that finished
processing can be added, including one that still needs review.
release_changes_change_unique keeps each change in one release. The
composite foreign keys on (id, organization_id, project_id) make the
database reject a change joining a release of another Project or tenant.
A decision is APPROVE or EDIT and carries the category, breaking flag, and
security flag the reviewer saw; a decision without security confirms the current one.
APPROVE must match the change's current classification
(409 classification_changed otherwise) and cannot confirm an Unknown
change. Both actions call ChangeReviewService.review, so the change records
the reviewer exactly as an Inbox review does, and a release_change_reviews
row records the release's decision, the reviewer, an optional note, and the
time. A later decision on the same change replaces the row. Rejecting a
change removes it from the release, and the cascade removes its decision.
Approval records the approver and time and requires a decision on every
change, so no approved release contains a change that still needs review.
Returning to draft deletes the decisions, the approval, and the notes; the
reviews and summaries on the changes stay. Discarding deletes the release, and the cascade makes its changes
available again.
Flyway V12 enforces the lifecycle in PostgreSQL too. Rows are added to
release_changes only while the release is a draft, are never updated, and
are deleted only before approval. Decisions are written only while the release
is in review and deleted only before approval. The triggers skip a release
that no longer exists, so discarding an approved release still cascades.
releases_approval_recorded keeps the approval columns together, requires
them on APPROVED, and forbids them on DRAFT and IN_REVIEW. Releases
published before V12 have no approval.
The planned release time is optional and must lie in the future. REST clients
send an ISO-8601 instant with an offset; the page's datetime-local input
sends a local time that is read as UTC, and pages show times in UTC.
ReleaseNotePreview groups an unpublished release's changes for the REST
preview field by category group: breaking changes first and only there, then
Features, Fixes, Performance, Documentation, Maintenance, and Other changes,
sorted by merge time. Titles drop a
leading Conventional Commit prefix. Pages instead preview each audience's note
(see Audiences and release notes).
Linked issues at review and folding
ADR-0041 adds two things to a release in review, and neither ever blocks approval or publication.
- Statuses as of review.
requestReviewqueues onelinked_issue_readsrow, or queues it again, and forgets what earlier reads found, keeping acceptances.LinkedIssueReadWorkerclaims it, gathers each distinct(tracker, key)of the release's changes throughChangeInboxService.changes, reads them from Jira or Linear with no transaction open, and records each read issue inrelease_linked_issues. While an issue is unread it retries after2^attemptseconds (at most 300), five attempts in all, then finishesFAILEDand the unread issues keep their recorded status. Each result publishesLinkedIssuesRead, which renders again anAPPROVEDrelease's notes that still follow their template. - One release, one writer at a time. Every transaction that writes a release or what
belongs to it locks the release's row first, before any other row
(
ReleaseRepository.lockByIdAndOrganizationIdAndProjectId,FOR NO KEY UPDATE). That covers each writing method ofReleaseServiceand the worker's transaction that records a read. An acceptance, a new review, and a read's result therefore run one after the other, each loading the rows the one before it committed, so none writes back a column it loaded stale and none inserts a row the other already inserted. With one lock taken first everywhere, none of them can deadlock another. The worker's claim and the read itself take no release lock, andFOR NO KEY UPDATElets other tables still insert rows that refer to the release (#119). - What a note gets.
IssueStatusesturns the rows into thestatus,recordedStatus, andstatusAtReviewof eachNoteIssue: a status is given only when its category isdone, or when a person accepted that very status; otherwise all three are empty.SectionValuelets{{#status}} ({{status}}){{/status}}print the value in Mustache standards mode. An acceptance names the status the person saw, and one that no longer matches the last read is409 linked_issue_status_changed.ReleaseView.openLinkedIssuesis the warning, the open issues nobody accepted, andacceptedLinkedIssuesthe open ones whose current status matches the accepted one, which the Review tab lists withaccepter_nameandaccepted_atwhile the release is in review or approved. Both come from the sameLinkedIssueStatusViews the API returns. - Folding suggestions.
ReleaseServicecomputes them from stored data alone while the release isIN_REVIEW: a Jira or Linear change of the release whose key a GitHub or GitLab change of the release lists among its linked issues, or whichChangeFoldingService.confirmedDuplicatespairs with one. A suggestion with a row inrelease_fold_decisionsis not offered again. Accepting runs, in one transaction,ChangeFoldingService.foldIssue(which adds the tracker change's issue to the code change when it lacks it), carries the tracker change's breaking and security flags into the code change when that changes one (ChangeReviewService.reviewby the person, and arelease_change_reviewsrowEDITwithfolded_change_id; refused for an Unknown code change), removes the tracker change from the release, excludes it throughChangeExclusionServicewhen the person chose to (administrators, with a non-blank reason), then records the decision. An issue the fold added queues the release's read again; a claim takes only the issues with no read at this review, so a retry or a fold asks the tracker for what is missing and nothing else.
Audiences and release notes
audience owns the Organization's audiences and their templates; see
ADR-0011. AudienceService serves the
REST and page controllers (administrator only by URL rule), the AI request
(briefs), and the release service (list). Creating and deleting audiences
lock the Organization's audience rows, so the limits of one and twenty hold
under concurrent requests. Release notes, automation rule actions, and automation
action runs each hold a foreign key to the audience; before deleting,
AudienceRepository.use asks which of them still names it, and the answer is
409 audience_in_use with a detail of its own for each. The foreign keys stay the
last word, and a violation of any of the three found by the delete itself is
reported the same way. An archived rule's actions are not removed to make room,
because run history has to keep naming what it delivered to.
AudiencePresets holds the four shipped audiences (operator, contributor,
end_user, and support), with names and template labels from
messages/audience-presets{,_vi}.properties. Registration seeds all four. V13
seeded the first three, with the values of its time, for Organizations that existed
before, which keep their templates and intents until a preset is reset, and can add
support themselves; a migration test compares them with those values.
resetToPreset takes the shipped audience with the audience's code, whether
registration seeded it or an administrator added it, and sets preset, so an
added support follows the preset in later language variants and resets; a code
nothing ships is refused with audience_not_preset, and the Audiences page offers
the reset exactly when AudiencePresets.shipped holds for the code. Each intent
ends by saying when a change is none for its audience, and the operator intent
names something to watch only when the change or the Project context does. The
shipped templates lead with **{{headline}}**, label a migration step by its kind
through the migration<Kind> sections, keeping the neutral label for
unspecified, keep their detail lines inside {{^brief}}, and print a required
step outside it; the end-user one prints a step only when it is required.
Retired audiences
ADR-0044 adds retirement beside deletion.
AudienceService.retire runs in its own transaction: it locks every audience row of the
Organization, refuses the last active one with audience_last_active, sets the three
retired_* columns, and inserts an audience_status_changes row with the
administrator's name at the time; restore clears the columns and records the return.
The audience_definitions_keep_an_active_audience constraint trigger is the backstop: it
fires deferred, at commit, on any update that changes retired_at, locks the
Organization row, and raises when no active audience is left, so of two transactions
retiring the last two, the second waits for the first and fails. retire maps that
commit-time failure to the same 409. Deleting the last active audience is refused with
audience_last; a retired one can be deleted when nothing names it.
briefs and active leave retired audiences out, so the AI request, note writing, and
note previews never see one, and retiredCodes tells the writer which narratives not to
translate. A narrative a retired audience already has is kept: the summary edit puts the
request's active narratives over the stored ones, so leaving a retired code out no longer
erases it. Re-rendering an approved release leaves out the retired audiences that have no
note in it, so a release approved before a retirement keeps that note. With nothing
retired, briefs, translation texts, and notes are byte for byte what they were.
MissingNarratives lists, for a release in review or approved, the changes the AI
classified that have no narrative for some active audience, with the rough token size of
the request that would ask for them: the system prompt, the user message, and the
response schema, over four, computed without sending anything. Asking sends that one
request with the same evidence as the classification and only the missing audiences, and
Change.addMissingNarratives adds only the codes asked for that are still absent, so
nothing a person wrote and no other field changes. Each request is made only when a
person asks.
AudienceTemplate wraps JMustache in standards mode with strict sections,
empty strings as false, and no escaping, because the output is Markdown. It
validates a template on save by compiling it and rendering sample values, and
renders one AudienceItem (whatChanged, whyChanged, technicalDetail,
migrationStep, migrationKind, limitations, narrative, headline,
relevance, reference, pullRequestNumber, pullRequestUrl, linkedIssues),
whose context adds one boolean section per migration kind (migrationRequired,
migrationConditional, migrationRecommended, migrationUnspecified) and
brief, since Mustache cannot compare values. headline falls back to
whatChanged, so it always has a value, and relevance is brief or full.
audience cannot see MigrationKind or Relevance, so each arrives as its value. reference comes from ChangeView.reference(): #n for GitHub, !n
for GitLab, and for Jira and Linear the issue key read from the issue address
ReleaseFlow stored, falling back to #n. The Change Inbox and release pages show the
same label.
MarkdownHtml renders Markdown for pages with CommonMark: raw HTML is
escaped, link targets are sanitized and marked
rel="nofollow noopener noreferrer", and images become links.
ReleaseNoteDigest is a pure function that writes one audience's note from the
changes that concern it (concerns): every breaking change, and every other
change whose AudienceNarrative for the audience is not NONE. A change with no
narrative for the audience is FULL, and NONE on a breaking change reads as
BRIEF (ADR-0035). The note has:
- the title and the escaped release summary;
- "What's New", with a count per section of what the note shows, joined by the bundle's list pattern, and a breaking warning;
- sections in the order breaking (the flag), security (the flag, ADR-0037), features, fixes, performance, documentation, maintenance, other, each item rendered by the template and its headings demoted two levels outside fenced code;
- the audience's footer, rendered once with
AudienceTemplate.renderFooter.
Placement is exclusive: a breaking change is in Breaking, a security change that is not
breaking in Security, and any other in its group's section, so the counts add up to the
total. A change that is both gets the bundle's securityMarker after its list marker,
whatever the template prints. concerns also keeps a security change for the
operator, contributor, and support codes, where NONE reads as BRIEF. The
breaking warning uses breakingWarning.guide, which links the release's upgrade guide,
when it has one.
When nothing concerns the audience, the note is the title, the summary, and the
bundle's nothingForAudience line; approval still writes it, and an automation
action delivers it like any other.
Labels come from messages/release-note{,_vi}.properties, chosen by the note's
language with an English fallback, and counts use java.text choice formats.
Without a summary, what changed is the escaped pull request title. Summary and
narrative text keeps its Markdown, but ReleaseNoteMarkdown.escapeRawHtml
backslash-escapes the < of whatever a CommonMark parser reads as raw HTML (an
inline tag, or every tag of an HTML block), re-parsing until none is left, so a
placeholder such as <id> shows on GitHub as it does on the release page. Code,
autolinks, emphasis, links, and a bare < are left alone, the result is idempotent,
and this happens only as the note is written: the stored text, and what is sent to
translation, keep what the AI or a person wrote.
ReleaseService uses it as follows:
- Approval renders one
AudienceReleaseNoteper audience and release note language from the current changes, snapshots the audience's code, name, template and footer for that language, and the language, and inserts the notes after the release row is flushed as approved (see Release note languages and translation). A render failure aborts approval with409 release_note_render_failed. Before that,ReleaseNotePreview.needsSummaryfinds every change whose title, without its Conventional Commit prefix, issue keys, and#nor!n, has fewer than three words, and that has neither a summary a person wrote nor an AI summary of a description of at least ten words (HTML comments not counted) with a context the AI did not find insufficient, and approval answers409 change_summary_requirednaming their references (ADR-0035). The release page marks them Needs a summary and opens their Edit summary. - Editing a note is allowed only while approved. It stores the text and the
editor and turns off
auto_rerender. - Editing a summary is allowed during review or after approval, for a
change of the release. It calls
ChangeSummaryService.edit, which keeps narratives only for current audience codes, and only those that say more than having none, and then renders every automatic note again from its stored template and footer.ChangeSummaryRequest.Narrativebindsnarratives[<code>].relevance,.headline, and.bodyfrom the page, and from JSON either that object or a plain string (a delegating@JsonCreator), which is a full body. A person's headline is collapsed onto one line. - Storage.
changes.audience_narrativesholds oneAudienceNarrativeobject per audience code; FlywayV32rewrote each string stored before as{"relevance": "FULL", "headline": "", "body": <string>}.ChangeViewreturns them asaudienceNarrativeDetails, and keepsaudienceNarrativesas audience code to body so REST clients written before keep working. - Returning to draft deletes the notes.
- Publishing requires notes (
409 release_notes_missing). - Previews render the current changes with the current templates and store nothing.
The release_audience_notes_follow_release_status trigger allows inserts and
updates only while the release is approved. An update may change only the
content and the edit record, and deletes are rejected once the release is
published. release_audience_notes_edit_recorded ties auto_rerender to the
editor columns.
Security changes and release-wide note structure
ADR-0037 adds a security flag beside breaking and a footer per audience; see ADR-0037.
- Rules.
ChangeClassifiersetssecurityfor a label equal, ignoring case and surrounding whitespace, tosecurity,security-fix,security fix, orvulnerability, and forCVE-\d{4}-\d{4,}(case-insensitive) in the title, the description, or a label, and records the match as a reason. Security forces review like breaking. - AI. The response schema requires one boolean,
security_change, and the instructions say what it means; nothing else in the request changed. The parser rejects an answer without a boolean there, likebreaking_change.ChangeAiMergestores the rule result OR the AI's, so the AI can add the flag but never clear what a rule found, and a security change stays in review. A person's review is never asked of the AI again (isAiEligible), so the AI never clears what a person set either. - Database. Flyway
V34addschanges.security(false for every change recorded before) and redefineschanges_review_requiredso a security change leaves review only with a recorded review. - Releases.
upgrade_guide_urlis checked byReleaseLinkBuilder.validatedUpgradeGuideUrl(400 invalid_upgrade_guide_url), andprevious_release_idmust be a published release of the same Project (400 invalid_previous_release), which the composite foreign key and thereleases_previous_release_publishedtrigger hold in the database too.ReleaseRequestrecords whether each field was sent, so an older caller's update keeps both and a create withoutpreviousReleaseIdtakes the Project's most recently published release bypublished_at. The pages always send both. - Footers. An audience and each language variant have a
footer_template_body;AudienceTemplate.validateFootercompiles and renders it withReleaseLinks.SAMPLE, under the same compiler, with thetemplate_invalidcontract and the form field the exception names. JMustache in standards mode looks a name up only in the innermost context, so each footer value is aFooterValue: it prints as its text, and as a section it renders its body, only when not empty, in a scope that still holds every footer value and prints as its own text for{{.}}. Registration seeds the shipped footers,resetToPresetrestores them in every language, andV34gave existing operator and contributor audiences the same text (a migration test compares them). Approval snapshots the footer intofooter_template_snapshot; notes written before have a blank one. - Links.
ReleaseLinkBuilderreads the Project's sources from the database and keeps GitHub and GitLab ones; with exactly one, it buildscompareUrlfrom the previous release's version and this one's, andreleaseUrlfrom this one's, each a path segment encoded byUriUtilsand used as the tag name exactly as written. It makes no provider call, so rendering a note, a preview included, never touches the network.ReleaseNoteDigestescapes the versions for Markdown and percent-encodes the parentheses of the upgrade guide before the footer sees them.
Release note languages and translation
ADR-0015 writes a note per audience and release note language; see ADR-0015.
- Languages.
ReleaseLanguageService(packageaudience) stores the Organization's 1–5 target languages inorganization_translation_settings, canonicalized byOutputLanguage.parse. Without a row, the output language is the only one. - Templates.
audience_template_variantsholds an audience's template for one language, unique per audience and language and deleted with the audience.AudienceView.templateFor(language)returns the variant or the main template. Saving the languages, and creating an audience, add the missing variants for every target language whose primary language differs from the output language: the shipped template in that language for a preset, a copy of the main template otherwise. - Jobs. The
translationpackage depends on no other domain package butproject, for the Project's context (ADR-0035).TranslationService.ensuretouches only the database, so approval can call it in its transaction. It returns the texts at once when the source and target share a primary language or all are blank, returns the existing job's state for the same change, target, andinput_hash(SHA-256 of the source language, the texts sorted by key, and the Project's context when there is one), and otherwise creates atranslation_jobsrow that keeps that context (translation_jobs.context, FlywayV30):SUCCEEDEDwhen every text is intranslation_cache,FAILED(translation_disabled) without a provider, andPENDINGotherwise. - Worker.
TranslationWorkerruns every second. It claims one due job withFOR UPDATE SKIP LOCKED, looks its texts up in the cache, and sends only the missing ones, each once and in the order of their keys, so every run sends the same list, toDeepLTranslatoroutside any transaction:POST /v2/translatewithDeepL-Auth-Key, the job's context ascontextwhen it has one, batches of at most 50 texts and 120 KiB, source as the primary language and English or Portuguese targets with a region. A 429, a 5xx, or a network failure is retried up to five attempts withmin(300, 2^attempt)seconds of backoff; 403, 456, other 4xx, and a response with the wrong number of translations fail at once. Only fixed codes are stored. The result transaction writes the output and the cache and publishesTranslationFinished; aRUNNINGjob left for ten minutes becomesPENDINGagain. - Notes.
ReleaseNoteWriterlocalizes the release's changes for one language: a summarized change in another language is replaced byChangeView.withContentwith its translated summary and narratives once ready, and keeps its own text otherwise. A narrative's body and headline are the textsnarrative.<code>andheadline.<code>; its relevance is kept from the source. A blank headline is not sent, so a narrative without one hashes as it did before headlines existed. The release's own summary goes throughTranslationService.ensureForRelease, a job whoserelease_idis set, from the Organization's output language; the note prints the translation and the release keeps what was typed. The note takes the worst state of its changes and its summary (FAILEDoverPENDINGoverREADY) inrelease_audience_notes.translation_status. Approval writes a note per target language and audience fromtemplateFor;ReleaseServicelistens toTranslationFinishedin the worker's transaction and renders the automatic notes of the approved release that holds the change, or whose summary it was, in that language again. Editing a summary renders every automatic note again, which queues the new text.retryTranslationsrestarts the failed jobs of an approved release's current texts. Editing a note by hand makes itREADY. - Glossary. ADR-0036 adds an Organization glossary; see
ADR-0036. Its page and API controllers sit in
audience, beside the release note languages they read, sotranslationstill depends on no domain package butproject.GlossaryServicekeeps kept terms and fixed translations (glossary_kept_terms,glossary_translations, FlywayV33) and builds a pair's dictionary: every kept term mapped to itself and the pair's fixed translations over them, sorted, as TSV. Its version is the SHA-256 of that TSV, empty for none, andTranslationTexts.inputHashandtextHashadd it beside the context only when it is not empty, so an Organization without a glossary hashes as before.ensurerecords the version on the job and, while the job is pending, sets the pair'sglossary_syncsrow to want it, locked and inserted withON CONFLICT DO NOTHING.lockNextDueskips a job whose pair isPENDINGorRUNNINGfor its version.GlossarySyncWorkerclaims a due row withSKIP LOCKED, only while no other pair of the Organization isRUNNING, under the lock oftranslation_glossaries, and outside any transaction asksGET /v3/languages?resource=glossary(a pair is supported when both languages are listed;featuresis not read), thenPOST /v3/glossariesorPUT /v3/glossaries/{id}/dictionaries, creating the glossary again on a404. A claim syncs the dictionary as it stands, so an edit since the want cannot loop. 429, every 5xx, and network failures are retried like translations; 456, the plan's glossaries, and every other 4xx fail at once. The translation worker sendsglossary_idonly when the row isSYNCEDat the job's version and the attempt is not the last, records the outcome on the job, and caches a text under the version it was translated with. A400with a glossary sends the dictionary again and retries.UntranslatedGuardchecks every answer for Vietnamese and non-Latin targets after removing kept terms, fixed targets, code spans, URLs, paths, and capitalized identifiers; an answer that fails with the glossary is translated again without it in the same attempt (glossary_answer_untranslated), and one that fails without it fails the job withuntranslatedand is never cached.TranslationJob.succeedthen passes each text of its output, from DeepL or the cache, throughSourceForms.restore(ADR-0040): a placeholder or lowercase hyphenated identifier of the source that the translation has in another letter case alone, and matches unambiguously, gets the source's form back. Code spans are restored first: a span of the answer whose text the source writes is kept, the source's spans are matched to kept spans occurrence by occurrence, and the answer's other spans get the unmatched source spans' text in order when the counts agree;SourceForms.unpairedSpansreports when they do not, and a text with a fence, a double-backtick span, or an odd number of backticks is left alone. The cache keeps DeepL's answer, and a lost placeholder or unpaired spans are only logged.ReleaseNoteWritercombines the jobs' outcomes per language (NOT_APPLIEDoverPENDINGoverAPPLIEDoverNONE) intorelease_audience_notes.glossary_status, andReleaseView.glossariesreports it per language.retryTranslationsalso restarts a failed sync and re-translates jobs that went without their glossary for a reason other than an unsupported pair. The glossary never reaches the AI request. - Publication.
publishrefuses a release with a note that is not ready (409 translations_not_ready), and thereleases_publish_ready_notestrigger refuses it in the database too. Notes are unique per release, audience, and language, and downloads are named<version>-<audience>-<language>.md. - Page. The release page shows a badge per note, a banner while notes are
translating or failed, and a Retry translations button. The
translationPollAlpine component reads the notes URL from a data attribute, polls it every three seconds for up to ten minutes, and reloads once no note is pending.
Release Note publication
ReleaseService.publish runs in one transaction. It requires an approved
release with notes that are all ready and marks it PUBLISHED with the publisher's ID, name, and
time; from then on the triggers freeze its audience notes. Releases published
before V13 have a single legacy release_notes snapshot of sections and
Markdown instead, which reads fall back to. Reads of a published release use
the stored notes, so reclassifying an included change afterwards never changes
what was published. See ADR-0005
and ADR-0011.
Immutability is enforced twice. The service rejects every operation on a
published release with 409 release_published. PostgreSQL triggers reject
UPDATE or DELETE on release_notes, UPDATE or DELETE on a PUBLISHED
release, and writes to its release_changes, release_change_reviews, and
release_audience_notes.
releases_publication_recorded keeps status, time, and publisher consistent.
releases_project_version_unique prevents a later release from reusing a
published version.
Automation
A Rule is an Organization's standing instruction: when this trigger fires, deliver the release note through these Actions, in order. A Rule without a project watches every project of the Organization. It starts disabled, because enabling it is what checks the deliveries can be made. See ADR-0020.
Rules and actions
automation_rules holds the name, unique per Organization
whatever the casing while the rule is active, the trigger, the optional project, and
the enabled and active flags. automation_rule_actions holds one step each: a
position from 0, the kind, the audience and language whose note it delivers, a JSONB
configuration, and an encrypted secret. The position is unique per rule and deferred to
commit, so reordering inside one transaction never collides with itself. A secret is
bound to the Organization, rule, action, and kind by AutomationSecrets, and is
write-only: responses and pages say only that one is configured.
Enabling
AutomationRuleService.enable checks, in order, the project's ownership,
every audience's ownership, language, and activity (automation_audience_retired), a
single connected GitHub source for a GitHub
Release action on a project-scoped rule, whether the deployment can carry the action out at
all, and the action's own configuration and decrypted secret.
Triggers
A rule fires when a release is published, when an administrator runs it,
on a cron schedule, before a planned release, or when another system calls its own
signed webhook. See ADR-0021.
What each trigger needs is columns on automation_rules, with a CHECK per trigger, so
a rule carries exactly what its own trigger uses and changing the trigger forgets the
rest.
From publication to runs
ReleaseService.publish publishes ReleasePublished
inside its own transaction. ReleasePublishedListener writes one
automation_publish_jobs row and does nothing else, so no rule can undo a publication.
AutomationWorker drains that outbox after the commit and creates one
automation_runs row per matching enabled rule, with an automation_action_runs row
per action carrying the note, configuration, and encrypted secret as they were. A
publication fires each rule once, and a repeated manual request returns the same run.
Schedules and reminders
AutomationTriggerWorker ticks every fifteen seconds and
only writes runs; it never calls a provider. A cron rule repeats one PUBLISHED
release on a six-field expression in an IANA time zone, and takes that release's
project as its own. The worker claims a due rule with FOR UPDATE SKIP LOCKED, writes
at most one run for the occurrence it found, and books the next firing from now, so
a deployment that was down owes one catch-up run rather than a queue of them. A
reminder rule watches APPROVED releases whose planned_release_at is within its
notice; the run answers the moment planned_release_at less that notice, so moving a
release earns exactly one more reminder and scanning again earns none. A rule with no
notice at all is answered within a short lookahead (PT15S). automation_runs
records that moment in scheduled_for, unique per rule and occurrence for a schedule
and per rule, release, and occurrence for a reminder. Both triggers accept Slack,
Microsoft Teams, and
email actions only: nobody is watching when a schedule goes off. Disabling or archiving
a rule clears next_fire_at, which the database also requires, so a rule that is off
is never claimed.
Called by another system
AutomationWebhookController answers
POST /webhooks/automation/{webhookId} with 202 and {runId, status, statusPath},
and GET …/runs/{runId} with the run's state; both are signed and neither is
authenticated. The signature is HMAC-SHA256, keyed by the rule's own 256-bit secret,
over the timestamp, the delivery UUID, the uppercase method, the request path, and the
hex SHA-256 of the raw body, one per line, compared in constant time within five
minutes of clock skew. A body over 64 KiB is refused before any rule is looked up. The
Organization is the rule's; the body names only a release, which must be published and
in the rule's project. The delivery UUID becomes the run's request_id, so a caller
that retries after a timeout is given its first run back. An unknown path, a disabled
rule, a stale moment, and a wrong signature all answer 401. The secret is bound to
the rule and its path by AutomationSecrets with its own purpose, shown once when the
rule is created and once more whenever
POST /api/automation/rules/{id}/webhook-secret/rotate replaces it, which keeps the
path and stops the old secret at once.
Worker
It ticks every second and drains what it finds. A claim takes the next
pending action of a run that is neither finished nor being cancelled, and only once
every earlier action has succeeded or been skipped, with FOR UPDATE OF action_run SKIP LOCKED. The
provider is called with no transaction open, and the result is written in a short
transaction that first checks the claim is still this worker's. An action whose audience
is retired is skipped with audience_retired before any provider is called; no metric is
recorded for it, since nothing was delivered. After that, and after an action with no
ready note fails with release_note_missing, an action whose release note still follows
its template is skipped with nothing_for_audience when no change the release includes
concerns its audience. ReleaseAccess.hasNothingFor decides it in one read-only
transaction, from the release's changes as they are then and ReleaseNoteDigest.concerns,
the rule that chose the note's changes; the note's text is never read, and a note a person
edited is always delivered (ADR-0035 and ADR-0044, amended 2026-11-19).
Outcomes
PENDING, RUNNING, SUCCEEDED, FAILED, UNKNOWN, CANCELLED, and, for an
action, SKIPPED, which counts as done: a run whose actions all succeeded or were skipped
succeeds. The first action that fails or ends unknown stops the ones behind it. An action whose
worker stopped becomes UNKNOWN after five minutes and is never sent again on its own;
a person repeating it confirms the duplicate. A retry resets only the first action that
did not succeed. Cancelling lets the action already running record its result and stops
the rest. Only an error code is stored, never a provider's words.
Actions
No outbound client follows a redirect, and a redirect is never a delivery.
- Public changelog publishes the note on ReleaseFlow's own pages and is the only action that reaches no provider; see Public changelog.
- GitHub Release borrows the project's own source token, publishes the note as the
release of the version's tag, and marks the body with
<!-- releaseflow-action:{id} -->so a repeat knows its own work from somebody else's.AutomationRunFactoryrecords the repository of the project's one connected GitHub source, or of its one disconnected source when none is connected (SourceAccess.soleExternalKey); when that source is disconnected at delivery the action fails asgithub_source_disconnectedbefore any call, and a retry after the reconnect succeeds. A rule view carriesgitHubSourceMissingwhile an enabled rule's project has no connected GitHub source to lend. - Slack posts through an incoming webhook whose origin the deployment allows,
checked again before every delivery, up to 39,000 characters. A redirect fails the
action as
slack_rejected, as does any 4xx, while a 5xx may have posted before failing to answer and is recorded as unknown. The note is rewritten from Markdown into Slack's mrkdwn — headings and strong text as*bold*, links as<url|text>for http, https, and mailto only, lists as bullets — and every&,<, and>of its own text is escaped, so no title can mention a person or<!channel>. - Email sends through the deployment's SMTP server to between 1 and 100 addresses, as multipart/alternative: the note's Markdown for plain-text readers, and the HTML the Confluence and Zendesk actions receive, with raw HTML escaped and images turned into links so opening the mail loads nothing.
- Notion files the note as a child page under a page id the action names, against the API version the deployment pins; Notion's own address is deployment configuration, so no request chooses it.
- Confluence creates a page in a Cloud space, authenticated by the account's email
and an API token, with the note rendered by
MarkdownHtmlinto the storage body and an<!-- releaseflow-action:{id} -->comment saying which run wrote it — provenance only, since nothing reads it back. Its site is checked again before every delivery, and must be exactly one label beneathatlassian.netover HTTPS with nothing after the host. Notion and Confluence both bound the payload before any network call — 450,000 bytes for Notion, 2,000,000 for Confluence — and map a 4xx toFAILED, a 5xx or a lost connection toUNKNOWN, and a redirect toFAILED, because no page was written wherever it pointed. - Microsoft Teams posts through a Workflows callback whose URL is its secret and
carries its own signature, checked against the Workflows shape again before every
delivery, with 28 KiB measured on the written request rather than the message. The
note is sent as plain text:
TeamsTextdrops its Markdown, so what the note escaped (\<id>,\*bold\*) reads as written, without the backslash. - Zendesk makes two calls: a short-lived client-credentials token, then a Help
Center article from the same
MarkdownHtmloutput, bounded at 1,000,000 bytes. Because nothing is published until the second call, every way the first can fail isFAILED— including a 5xx — while the second follows the usual rule, and a 2xx naming no article isUNKNOWN.
An action with no note
A release with no ready note for an action's
audience and language gives the action no snapshot, and it fails as
release_note_missing when the worker reaches it. The release publishes either way.
Controllers
AutomationRuleApiController and AutomationRunApiController serve
/api/automation/**, and AutomationPageController serves /automation; both are
administrator-only by URL rule. POST /api/automation/rules/cron-preview answers when a
schedule would next run, and the page has the same button. The webhook paths are the
exception: they live under /webhooks/**, where the signature is the identity. The run history pages with AutomationRunPage
(items, page, size, total), which is the only paged list in ReleaseFlow.
Public changelog
An Organization's changelog is the one destination ReleaseFlow serves itself, for people who have no account. See ADR-0022.
- A slug names an Organization in a URL. One DNS label, unique across the
deployment, checked by
OrganizationSlug.parseand by a CHECK constraint.V24gives every Organization one made from its name, numbering collisions by age; registration derives one the same way.PUT /api/organization/slugand the card on/projectsmove it, which is an administrator's decision because links already shared stop working. - An entry is written only by a
PUBLIC_CHANGELOGaction, for one audience and language, and copies the Organization's name and slug, the project's name, the version, the audience, and the note. Renaming any of those later never rewrites it, and a trigger refuses every update and delete, exactly asrelease_notesdoes. - A repeat is free; different words are refused. An entry is unique per Organization,
release, audience, and language, and per action run, so retrying an action finds its own
entry and succeeds. A second rule offering different content for the same release,
audience, and language fails as
public_changelog_conflict. This is the only action a repeat is safe for, because the destination is ReleaseFlow's own database — which is also why it is the only executor that opens a transaction rather than calling out. - Reading is anonymous and cached.
PublicChangelogControllerservesGET /changelog/{slug}(public, max-age=300),GET /changelog/{slug}/releases/{entryId}(public, max-age=86400, immutable, with the entry's identifier as its ETag and304for a reader who has it), andGET /changelog/{slug}/rss.xml(RSS 2.0, at most 50 entries)./changelog/**has its own security chain: GET only, no request cache, and no session, so looking never earns a cookie. Nothing there is excused from CSRF, and nothing needs to be: the chain denies every method a token would have been required for. An address nobody answers is404, and an Organization with nothing published looks the same as one that does not exist. - The list groups languages.
PublicChangelogService.findFeedturns the 50 newest entries into one card per release and audience, holding each language in publication order and named byEntryView.languageName()in that language. An entry page names its own language only, because its immutable cache would keep a sibling published later off it. - The note is rendered by
MarkdownHtml, the same renderer the application's own pages use: raw HTML escaped, link targets sanitized, images turned into plain links. The RSSdescriptioncarries that HTML, escaped into the document by the JDK's XML writer. - Links come from configuration.
releaseflow.public.base-urlis where this deployment is reached;releaseflow.public.changelog-base-domain, when set, serves each Organization at{slug}.{domain}throughPublicChangelogHostRoutingFilter, which rewrites exactly three paths for exactly one label, for GET only, before Spring Security sees the request. AHostheader chooses which slug to look up and decides nothing else; no link ReleaseFlow writes ever comes from a request.
Workspace overview
OverviewService in the overview capability owns no data: it asks ProjectService,
ChangeInboxService and ReleaseService for counts and composes them
(ADR-0028). It also passes on the selected
Project's sources with their health, which the page lists beside the figures; they are
not a step and do not change which one is offered. Both counts are aggregate queries
rather than lists counted in Java.
NextStep.of(...) decides the one step a person is offered, in a fixed order: no project,
no source, no changes, changes in no release, a review to finish, a release to publish, a
draft to continue, nothing waiting. The order belongs to the step rather than to the page,
so a unit test covers every branch.
SelectedProject remembers the Project somebody was last looking at in the
releaseflow_project cookie, so a page reached without ?project= opens on it instead of
on whichever Project is first. PageModelAdvice marks the Project named by a resource
path first, then a query, then the remembered Project, and supplies a safe switch target:
the change list, the release list, or the overview. The cookie carries no authority: the
Project is still looked up against the principal's Organization, and one that does not
belong there is simply not among those offered. A page that owns a Project resource still
does its own tenant-scoped lookup and reports a cross-tenant URL as not found.
Error pages
UnknownAddressAdvice answers an address that matches nothing in the kind the caller asked
for: a browser that names text/html gets the error page, and a fetch, a REST client, or
anything under /api keeps the Problem Details that spring.mvc.problemdetails.enabled
produces. HtmlErrorController renders what the container's error dispatch forwards —
a refusal from the security chain, or a fault. Three statuses have wording of their own;
anything else is shown as a fault, and the exception behind it never reaches the page.
An address under /api that reaches the error dispatch, such as an exception
ApiExceptionHandler has no handler for, is answered with Problem Details instead:
authentication_required, access_denied, not_found, internal_error for a 5xx, or
request_failed, with fixed wording. FrameworkErrorAdvice does the same for the
refusals Spring MVC raises before a controller runs: a method the address does not take
(method_not_allowed), a body type it does not read (unsupported_media_type), and a
missing or unconvertible parameter (invalid_parameter). A browser asking for a page
gets the error page for that status instead.
A page that names something the Organization does not have — a Project, release, change,
audience, rule, run, invitation, or any other ResourceNotFoundException — is the same
404 page rather than itself with an alert, because there is nothing on it to act on.
PageExceptionAdvice renders it with one more line in the failure's own words, such as
"Release was not found.", and never says whether the thing exists in another
Organization. ApiExceptionHandler runs first for every API controller, so the API keeps
each kind's own Problem Details code.
A form whose CSRF token no longer matches is not a refusal of the person. When the
session behind it has ended, ApiAccessDeniedHandler sends the browser to
/login?expired, which says nothing was saved; when the person is still signed in
(another tab signed in again), the 403 page says the form is out of date instead of
that the page belongs to somebody else. Either way the request never reached a
controller. CSRF protection itself is unchanged, and /api keeps access_denied.
User interface
Pages are server-rendered Thymeleaf templates composed with the Layout Dialect:
layout/auth frames the home, sign-in, and registration screens, layout/main
provides the signed-in sidebar shell, and layout/public frames the anonymous
changelog. PageModelAdvice supplies the signed-in viewer, the current path, the
Project switch target and choices, the languages the picker offers, and the language
this page is being written in. The mobile sidebar is an Alpine disclosure with a real
button, trapped focus, Escape handling, and focus restoration; its Project switcher
posts the same GET form as the desktop header.
A shared Thymeleaf brand fragment renders both full wordmarks. CSS selects the light-
or dark-background asset from the resolved data-theme, so a saved or manually toggled
theme changes the logo without another script or a second theme source of truth. The
compact logo mark remains the SVG favicon and the mark beside an Organization name on
its public changelog.
The stylesheet is compiled from Tailwind CSS 4 and DaisyUI 5 during the Maven
build, which installs a pinned Node.js through frontend-maven-plugin.
Alpine.js, served from a WebJar, handles only presentation behavior; forms post
to the same controllers and application services as before. app.js holds no
wording at all: components that show a label read it from a data-
attribute the template rendered, which is also how server data stays out of an
Alpine expression. See ADR-0003.
A dense table becomes one card per row below 640 px, each cell carrying its own
heading, and a 44 px touch-target floor covers controls and disclosure summaries.
Field errors are server-rendered with aria-invalid and aria-describedby; the small
script focuses the first invalid control after a failed submission. Consequential
automation actions use native details confirmations, and conditional delivery fields
remain visible when JavaScript is unavailable. What just happened is said in a toast
that is dismissed by hand: WCAG 2.2.1 asks that nothing disappear on somebody who
reads slowly. Every alert and toast comes from fragments/alert.html and
fragments/toast.html in one of four severities — success, info, warning, error — each
with its own colour and icon; only an error is announced as role="alert", and a
severity outside the four fails the page. The page around an alert decides where it
sits, its id, and any Alpine state; the fragment decides how it looks.
A controller never hands a page a finished sentence. It hands it a UiNotice — a
severity, a bundle key, and the values the sentence fills in — and the page writes it in
the reader's language as it renders. What a successful form did travels across its
redirect as the notice flash attribute, which the main layout shows as a toast on
whichever page the redirect lands on and nowhere else, so reloading does not say it
again. A failure the page shows in place is the pageNotice model attribute, and a
failure that belongs to a field or to a form is a binding error carrying the failure's
own key and values. The sign-in page is the one exception: signing out ends the session
a flash attribute would travel in, so it still reads ?logout, ?registered,
?invited, and ?expired.
The server is the only judge of a form. Every form that takes input carries
novalidate, so the browser never stops a submission with a bubble of its own and
whatever was sent is answered in the reader's language; required stays for assistive
technology, and the stylesheet draws a * beside a required field's label with empty
alternative text. A form that fails comes back with status 400 (409 for a conflict),
each field's error under it through fragments/form :: fieldError, and, on a form of
more than one field, fragments/form :: errorSummary above it saying how many fields
need a change and listing any error that belongs to the form as a whole. A value that
cannot be converted, such as text for a number, is reported through the bundle's
typeMismatch keys. A form repeated on one page — a Project's source, a change's
decision or summary, a note, a category row — shows its errors only on the copy that was
sent, which the controller names (failingChangeId and the like). A refusal from a
service that is about one field lands under that field: an automation failure names the
rule property or the action row it is about, the row counted among the rows the form
showed rather than among the ones filled in. Two browser habits are handled on purpose:
an unticked checkbox sends nothing, so a form that needs false sends Spring's
_breaking marker; and a date and time typed only in part is sent as nothing, so an
empty planned release time is an unfinished field, while clearing the schedule is a
button of its own.
Clipboard feedback is an aria-live status; when the Clipboard API refuses a write,
the source is selected and the page explains the manual fallback. Translation polling
keeps retrying transient read failures for ten minutes, then stops its timer and spinner
and offers a localized reload action instead of looking busy forever.
Playwright drives the real application through the demo Compose stack, with
@axe-core/playwright failing the build on any WCAG 2 A/AA, 2.1 A/AA or 2.2 AA
violation, at 360 px in the light theme and 1440 px in the dark one. The page sweep runs
in both interface languages and also checks horizontal overflow and disclosure target
sizes; interaction cases cover navigation focus, Project switching, validation focus,
clipboard fallback, polling timeout, confirmations, and the no-JavaScript form path.
Three suites cover the release pipeline, invitations, and every page. The only stand-in is
for providers: tests/e2e/compose.yaml adds tests/e2e/provider-stand-in.mjs, a Jira that
answers a project and an issue still open and a GitHub that accepts a token, so the suite
reaches a release's linked-issue sections. There are no JavaScript
unit tests, and deliberately so: what is left in app.js only means anything in a
page.
Interface language
Every word a person reads comes from messages/ui.properties and
messages/ui_vi.properties (ADR-0027). UiLanguages
reads RELEASEFLOW_UI_LANGUAGES once at startup, narrows each entry to a primary
subtag, and refuses a list that names no usable language.
UiLocaleResolver picks the language of a request in one order — a ?lang= query
parameter on a GET, the releaseflow_lang cookie, app_users.ui_locale,
Accept-Language, then the first configured language — narrowing each step to a
language this deployment ships and caching the result on the request. Only a GET reads
the parameter, so a form-encoded body a signed webhook has to verify is never consumed.
UiLanguageParameterInterceptor keeps a supported ?lang= in the cookie, never on the
account; an unsupported one is ignored. It is not registered on /changelog/**, whose
pages are cached publicly, so there the parameter changes only that page. The account's choice is read as it is now,
one column by primary key through UiLocaleService, and only when neither the parameter
nor the cookie answered; Spring MVC resolves the locale only when something asks for it,
and the resolver keeps its answer on the request
(ADR-0034). A change writes the cookie too,
and the cookie outranks the account.
UiLocaleService saves the choice, UiLocaleApiController answers
GET|PUT /api/me/ui-locale, and UiLocalePageController backs the picker in the
user menu. A public changelog request reaches only the cookie, Accept-Language
and fallback steps, so anonymous reading still creates no session and reads no
account, and the published note keeps the language it was published in. Those
pages are cached publicly and declare Vary: Accept-Language, Cookie; the RSS
feed is one shared document and stays English.
Failures carry a key rather than a sentence: every user-facing exception extends
LocalizedException. UiMessages writes it in the reader's language for
ApiExceptionHandler; a page controller passes the key and its values on as a field
error, a UiNotice, or the not-found page's detail, and the template resolves them.
Bean Validation reads the same
bundle through a validator wired to a message source over messages/ui. A missing
key is served as the key itself, so a gap is visible rather than silently English.
Recorded evidence is not interface text. A stored AI failure, a classification reason, a review trigger's detail and a provider's own name stay as they were recorded; only the sentence around them is translated.
Security
Spring Security uses server-side sessions. Four filter chains divide the requests, in this order, and none of them switches CSRF protection off (ADR-0023):
| Order | Matches | Allows | CSRF | Session |
|---|---|---|---|---|
| 0 | Actuator endpoints, matched with EndpointRequest.toAnyEndpoint() on the management port | GET health and Prometheus; everything else denied | Exempted for these endpoints only: a scrape carries no cookie and could never send a token | None |
| 1 | /webhooks/** | POST to the GitHub, GitLab, Linear, and automation webhooks, and the signed GET of an automation run; everything else denied | Exempted with ignoringRequestMatchers("/webhooks/**"): every request is proven by an HMAC over itself and reads no cookie | None |
| 2 | /changelog/** | GET only | Nothing exempted; the methods a token guards are denied | None, and no request cache |
| 3 | Everything else | Public pages, registration, sign-in, invitations, and static files; the rest needs a session, and the administrator paths listed under Roles and invitations need an administrator | Required for every write, REST included | Server-side |
Thymeleaf inserts hidden tokens into forms; REST clients obtain a token from
GET /api/csrf. Anonymous API requests receive a 401 problem response instead of an
HTML redirect.
REST failures use application/problem+json and a stable code, while
UI validation displays the same application errors next to the relevant field.
The title and detail of a problem are written in the reader's language, and
the code never is: it is what a caller matches on. The 401 and 403 bodies the
security filter chain writes are localized the same way, from the request itself,
because that chain runs before Spring MVC has put a locale in place.
Session cookies are HttpOnly and SameSite=Lax; deployments using HTTPS must set
the secure-cookie environment switch.
Build, container, and CI
The Maven build is the only build: it runs the tests, compiles the stylesheet,
and packages target/releaseflow.jar. The POM's version is ${revision}, which
is 0.0.0-SNAPSHOT unless a build passes -Drevision; only the Release
workflow does, with the version of the tag it publishes, and the Dockerfile takes
it as the RELEASEFLOW_VERSION build argument. The JAR's manifest and the image's
org.opencontainers.image.version label carry it. The Dockerfile runs that build with the
release profile in a JDK stage and copies the JAR into a Temurin 21 JRE UBI
minimal image that runs as UID/GID 65534. The image health check calls the
management port, which reports the database too. docker-compose.demo.yml adds
PostgreSQL 17, Prometheus, and Grafana, publishes the application, Prometheus,
and Grafana on host loopback only, and requires the database password, the
credential master key, and Grafana's administrator password to be supplied.
The quickstart bundle runs a released image without the repository. The template
quickstart/compose.yaml holds the application and PostgreSQL only, on loopback,
with the image left unset; scripts/ci/package-quickstart.sh writes in an image
reference and checks the result stands on its own. The Release workflow packages
it with the digest it pushed, after the push and before the checksums, and attaches
compose.yaml and quickstart.sh to the release. quickstart.sh takes its
configuration only from the .env beside it: it writes one with fresh secrets on the
first run, never overwrites it, clears inherited RELEASEFLOW_* and COMPOSE_*
variables, passes Compose its project, file, and env file explicitly, and refuses a
database volume whose .env is gone. See
ADR-0031.
GitHub Actions workflows in .github/workflows gate pushes and pull requests
to develop and main, and ci.yml, container.yml, and docs.yml also pull
requests into release/** and hotfix/**: tests, audits, and the Playwright browser and accessibility
suite (ci.yml), CodeQL, dependency review, a full-history Gitleaks scan, and a
container workflow that builds the
image, scans it with Trivy, and smoke tests the Compose stack. Actions are
pinned to commit SHAs, images to digests, and downloaded tools to SHA-256
checksums. The container workflow also proves the management port is not
published and that all four metric families are being scraped, then runs the
quickstart bundle against the image it built: a taken port, a first run, a second
run with a hostile shell, and a database whose .env is gone. CI lints the shell
scripts with ShellCheck and runs the quickstart under bash 3.2 with stand-ins for
Docker. See ADR-0007.
Observability
What a deployment may know about itself, and no more. See ADR-0026.
- The management port is not a product endpoint. Actuator answers on
management.server.port(8081 by default), bound to loopback unless a deployment moves it onto a private address; the Compose stack does exactly that, on a network markedinternal: true, and never publishes the port. A security chain of its own, matched withEndpointRequest.toAnyEndpoint()rather than by path, permitsGETon health and Prometheus, denies the rest, and creates no session. The application port serves none of it. - Four metrics, all labels from finite sets.
ClassificationMetricsowns the count of committed classifications byneeds_human_review, the timer from a change arriving to its classification, and provider requests byproviderandoutcome;AutomationMetricsowns deliveries bytriggerandoutcome. Both build every series from enums in their constructors, so each exists at zero from startup and no tenant, entity, model, reference, or error text can become a label. - Counting follows the write. A classification is counted after its
transaction returns, a delivery after its outcome is durable and only while
this worker held the claim, and an action abandoned by a stopped worker is
counted as
unknownwhen recovery marks it so.FAILEDandUNKNOWNstay apart: an unconfirmed delivery may have arrived. - One decorator counts every provider request.
MeteredChangeClassifierwraps the configured classifier, so all three providers and every caller are counted alike, exactly once, and an answer that arrived but could not be read counts as the error it was.