Chuyển tới nội dung chính

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.

PackageCapability
statusThe public home page and GET /api/status
accountOrganizations, registration, members, invitations, sessions, the output language, the interface language, and the public changelog slug
projectProjects, integration sources, their credentials, and webhook verification
sourceThe provider-neutral vocabulary every source type shares
github, gitlab, linear, jiraOne API client per provider, shared by project, change, and (for GitHub) automation
changeWebhook intake, imports and polls, change processing, classification, AI, review, the Change Inbox, sensitive paths, and review signals
categoryThe category catalog and AI proposals
audienceAudiences, their templates, and the release note languages
translationTranslation jobs, the cache, the Organization glossary and its DeepL sync, and the DeepL client
releaseThe release lifecycle, release notes, and publication
automationRules, triggers, runs, and every delivery action
changelogThe anonymous public changelog
overviewThe workspace overview and the remembered Project
configurationSecurity, 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.changeRole and remove each run in one TransactionTemplate transaction that first locks the Organization row (OrganizationRepository.lockById, SELECT … FOR UPDATE), then counts its active administrators and refuses with LastAdministratorException (409 member_last_administrator) when none would remain. Demoting an administrator and removing anyone revoke the pending invitations that person made. Each change raises app_users.session_version and inserts a membership_changes row with the changer's ID and name. Removal sets removed_at and removed_by and clears password_hash; the row keeps its name and email.
  • The constraint trigger app_users_keep_an_administrator (deferred, on updates that change role or removed_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. MemberService maps that commit-time failure to the same 409.
  • MembershipSessionFilter sits in the main filter chain before AuthorizationFilter and is built there, never as a bean, so it is not also a servlet filter. For a ReleaseFlowPrincipal it reads session_version and removed_at by 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 /api request then continues anonymous and meets the API entry point's 401 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.

text
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.disconnect nulls webhook_id, the secret, the token, and next_poll_at, sets disconnected_at and disconnected_by, and publishes SourceDisconnected inside the same transaction. SourceDisconnectionListener in the change capability fails the source's PENDING or RETRY_SCHEDULED sync job as source_disconnected; SourceSyncWorker reads the credentials again before every page, so a running job stops at the next one. IntegrationSource.recordPoll, recordPollFailure, and recordSync do nothing for a disconnected source, so a job finishing late books nothing. With no webhook_id, a verifier finds no source and the path answers like an unknown one. SourceAccess.find, findByType, findSole, and findDuePolls skip disconnected sources, so a change still processing completes as NO_ACCESS_TOKEN, linked context and issue reads see no tracker, and ReleaseLinkBuilder and NextStep count connected code hosts and sources only.
  • Reconnect. reconnect reads 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's workspaceOf must still answer the stored workspace), and writes in a second: a new webhook_id and 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. create refuses a key its Project holds disconnected with 409 source_reconnect_required.
  • Rotation. generateSecret (GitHub, GitLab) and replaceSecret (Linear, or a whsec_ token GitLab generated for a signed source) replace the ciphertext under the same authenticated data, set secret_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 one UPDATE per source. The UPDATE adds to the stored count and applies only while secret_updated_at is 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. SourceViews builds every IntegrationSourceView with a SourceHealth. One native query per list computes, for each connected delivered source, the gaps between its WEBHOOK changes 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. SourcePageController serves /projects/{projectId}/sources/{sourceId}, its disconnect confirmation, the shown-once secret page, and the reconnect result. The confirmation names the enabled rules SourceTokenBorrowers reports — the project port that AutomationRuleService implements, so project never reaches into automation. fragments/source-health draws 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:

  1. GitHubWebhookVerifier in the project capability looks the integration up by the untrusted webhook ID. This is the one lookup without an Organization ID, as anticipated by ADR-0002.
  2. 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-256 in constant time. An unknown or malformed webhook ID, a missing or malformed header, a wrong signature, and an undecryptable secret all produce the same 401 webhook_signature_invalid response.
  3. Only then does GitHubWebhookService in the change capability parse the JSON. The Organization and Project come from the verified source; any tenant field in the payload is ignored. A repository.full_name that does not match the configured repository case-insensitively, or a pull request without one, is rejected with 422 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, SourceSyncWorker first calls JiraPollScheduler.scheduleDuePolls(now). For each Jira source whose next_poll_at has passed and which has no PENDING, RUNNING, or RETRY_SCHEDULED job, it inserts a JIRA_POLL row in source_sync_jobs with 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. JiraPollReader asks GET /rest/api/3/search/jql for project = "KEY" AND statusCategory = Done AND updated >= "…" ORDER BY updated ASC, 100 at a time, following nextPageToken. The token is the provider half of the job's SyncCursor. Each issue is judged on its resolutiondate (else updated) and goes through the same ChangeIntake.record(..., IMPORT) as an import, so an issue seen by two overlapping polls is recorded once.
  • Bookkeeping. A completed poll calls IntegrationSourceService.recordPoll, which moves poll_cursor_at to the window's end, sets next_poll_at one interval later, and marks the source ACTIVE. A poll that must wait keeps its cursor and marks the source ERROR; one that fails for good does the same and sets next_poll_at 15 minutes later, so the schedule resumes on its own. The source records jira_unavailable when Jira could not be reached.
  • Addresses. JiraSiteUrl accepts only an HTTPS atlassian.net host with no port, credentials, query, or fragment, and JiraApiClient checks 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.

WorkerEveryTableWork
ChangeProcessingWorkersecondchange_processing_jobsEnrich and classify a change
SourceSyncWorkersecondsource_sync_jobsHistory imports, and Jira polls that JiraPollScheduler books
TranslationWorkersecondtranslation_jobsDeepL translations of change summaries and release summaries
LinkedIssueReadWorker2 secondslinked_issue_readsRead a release's linked issues again when its review is requested
GlossarySyncWorkersecondglossary_syncsSend a language pair's glossary dictionary to DeepL, one sync per Organization at a time
AutomationWorkersecondautomation_publish_jobs, automation_action_runsTurn publications into runs, then deliver one action at a time
AutomationTriggerWorkerRELEASEFLOW_AUTOMATION_TRIGGER_DELAY (15 s)automation_rules, automation_runsBook 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:

  1. Jobs left ENRICHING for more than ten minutes return to PENDING; jobs left CLASSIFYING become FALLBACK_REQUIRED.
  2. One due PENDING or FALLBACK_REQUIRED job is locked with FOR UPDATE SKIP LOCKED. A FALLBACK_REQUIRED job is completed at once from the recorded files, with the rules and a CLASSIFIER_FALLBACK trigger, never asking the AI again. A PENDING job is marked ENRICHING, its attempt counted, and its claim time recorded, so several workers never take the same job.
  3. Without a transaction, SourceAccess supplies the coordinates and token of the change's source, and the SourceEnricher of 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. LinkedContextEnricher then 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.
  4. 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; finally ChangeAiMerge combines 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:

  1. 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, is NOT_CONFIGURED. Each tracker is found by type with SourceAccess.findByType, the oldest first.
  2. SourceEnricher.commitMessages lists at most 250 commit messages over three pages (GET /repos/{o}/{r}/pulls/{n}/commits or GET /api/v4/projects/{key}/merge_requests/{iid}/commits). They are evidence only: never stored, never sent to the AI.
  3. IssueKeys.extract finds 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.
  4. 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 at releaseflow.jira.description-max-characters; the status category is fields.status.statusCategory.key.
  5. 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 type completed or canceled is the category done. The team key is integration_sources.external_team_key; a source without one asks for it once (team(id:){key}) and keeps it through SourceAccess.rememberTeamKey, and a key it cannot read makes the change UNAVAILABLE.

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. SourceImportService queues a HISTORICAL_IMPORT row in source_sync_jobs for a source with a token, with its window, cursor :0 (the first page), and releaseflow.import.item-limit (500). The partial unique index source_sync_jobs_one_active allows one PENDING, RUNNING, or RETRY_SCHEDULED job per source; a second request returns 409 source_sync_in_progress. Resuming a PARTIAL or FAILED job puts it back to PENDING with its cursor, a zero imported count, and zero attempts.
  • Readers. A SourceHistoryReader per source type turns one page into normalized items, and SourceHistoryReaders fails at startup if a type that has a history lacks one. SourceType.supportsHistoryImport() says which types those are; Linear and Jira are not, so SourceImportService answers 409 source_import_not_supported and the Change Inbox does not list it. GitHubHistoryReader asks GET /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. GitLabHistoryReader asks GET /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. SourceSyncWorker runs every second (off in tests, like the change worker). It releases RUNNING jobs claimed more than ten minutes ago, claims one due job with FOR 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 through ChangeIntake.record(..., IMPORT), which creates the change and its processing job or reports a duplicate. At the item limit the job becomes PARTIAL with 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-After or an exhausted rate limit, waits min(Retry-After or the reset time, one hour); a 5xx or network failure waits min(300, 2^attempt) seconds; the fifth attempt fails. 401, 404, and other 403 responses fail at once and mark the source ERROR through IntegrationSourceService.recordSync, which also records last_sync_at and the error code, github_unavailable or gitlab_unavailable naming the provider that could not be reached. An unreadable item is skipped with a warning.
  • Changes. Imported changes have origin = IMPORT and no delivery_id, which changes_import_has_no_delivery enforces. 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.

SignalRuleEffect
Title type^(feat|fix|perf|docs|refactor|chore|ci|build|test)(scope)?(!)?: text, case-insensitiveFeature, Fix, Performance, Documentation, or Maintenance group
Title !Marker after the type or scopeBreaking
Labelenhancement, feature; bug, bugfix; performance; documentation, docs; dependencies, maintenance, chore, refactorCategory, only without a title type
Breaking labelbreaking-change, breaking change, breakingBreaking
FooterA description line starting with BREAKING CHANGE: or BREAKING-CHANGE:Breaking
FilesEvery changed file is in docs/ or ends in .md, .adoc, or .rstDocumentation, before the title type
Sensitive pathA changed or previous path matches releaseflow.classification.sensitive-paths or one of the Project's additionsSENSITIVE_PATH review trigger
No file listThe files could not be listedCHANGED_FILES_UNAVAILABLE review trigger
Sensitive wordThe source has no files at all, and the title or description contains breaking change, migration, security, auth, credential, password, or encryptionOne SENSITIVE_KEYWORD review trigger per match
Linked issuesCommits could not be read, or Jira would not show a mentioned issueLINKED_CONTEXT_UNAVAILABLE review trigger
Migration kindThe AI's migration kind did not match its step, and the parser corrected itMIGRATION_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:

  • OpenAiCompatibleClassifier serves openai (Chat Completions with a strict JSON Schema and store: false) and deepseek (the same API with json_object and the schema in the prompt), through RestClient;
  • AnthropicChangeClassifier serves anthropic through 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;
  • breaking is the rules' flag OR the AI's;
  • needs_review is 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 AI only 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 requires context_sufficiency with a score and reasons. The parser rounds and clamps the score and keeps at most five reasons.
    • ContextSufficiency.assess lowers 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.
    • ChangeAiMerge assesses only a successful answer and adds one CONTEXT_INSUFFICIENT trigger below the threshold.
    • changes_context_consistent keeps the three context columns together, in range, and present only with a successful AI attempt.
  • Possible duplicates.
    • DuplicateDetector runs 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.
    • DuplicateSimilarity compares 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_candidates rows (at most five, most similar first) and DUPLICATE_CANDIDATE triggers on the new change through Change.addReviewTriggers, which only adds.
    • DuplicateCandidateService lists pairs with both sides for the Inbox and REST, and records one decision per pair; a second decision is 409 duplicate_candidate_decided.

Category catalog​

category owns the catalog and the proposals; it depends on neither change nor release. See ADR-0012.

  • CategoryService serves 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).
  • CategoryRef is the snapshot a change stores: code, display name, and group. CategoryRef.normalize upper-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 category enum is their codes. suggested_category is always an object whose empty code means no proposal, which keeps OpenAI strict mode and Anthropic Structured Outputs simple.
  • AiClassificationParser rejects 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. ChangeAiMerge then adds a CATEGORY_SUGGESTION_PENDING trigger, and the worker, or the AI retry, stores the proposal through CategorySuggestionService.propose in the transaction that records the result.
  • CategorySuggestionService.decide checks 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.
    • CategorySuggestionDecisionListener in change gives the category to the change if it is still Unknown and unreviewed, with the source SUGGESTION. needs_review and 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, and category_definitions_unknown_is_system keep the catalog valid;
  • changes_category_valid keeps the snapshot valid, UNKNOWN always in the OTHER group;
  • changes_ai_state_consistent requires a successful AI attempt for the SUGGESTION source;
  • category_suggestions_decision_recorded keeps 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.

OperationAllowed inAlso requires
Edit version or summary, add changesDRAFTa processed change that is in no other release
Remove a change (reject during review)DRAFT, IN_REVIEW
Request reviewDRAFTat least one change; queues a read of its linked issues
Accept a linked issue's status, decide a folding suggestionIN_REVIEW (an acceptance also APPROVED)an issue or suggestion of this release
Record a decisionIN_REVIEWa change of this release
Approve (writes the audience notes)IN_REVIEWa decision on every change
Edit a change's summaryIN_REVIEW, APPROVEDa change of this release
Edit an audience noteAPPROVEDa note of this release
Return to draftIN_REVIEW, APPROVED
Schedule, discardany status before PUBLISHEDa future time, or none
PublishAPPROVEDits 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. requestReview queues one linked_issue_reads row, or queues it again, and forgets what earlier reads found, keeping acceptances. LinkedIssueReadWorker claims it, gathers each distinct (tracker, key) of the release's changes through ChangeInboxService.changes, reads them from Jira or Linear with no transaction open, and records each read issue in release_linked_issues. While an issue is unread it retries after 2^attempt seconds (at most 300), five attempts in all, then finishes FAILED and the unread issues keep their recorded status. Each result publishes LinkedIssuesRead, which renders again an APPROVED release'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 of ReleaseService and 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, and FOR NO KEY UPDATE lets other tables still insert rows that refer to the release (#119).
  • What a note gets. IssueStatuses turns the rows into the status, recordedStatus, and statusAtReview of each NoteIssue: a status is given only when its category is done, or when a person accepted that very status; otherwise all three are empty. SectionValue lets {{#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 is 409 linked_issue_status_changed. ReleaseView.openLinkedIssues is the warning, the open issues nobody accepted, and acceptedLinkedIssues the open ones whose current status matches the accepted one, which the Review tab lists with accepter_name and accepted_at while the release is in review or approved. Both come from the same LinkedIssueStatusViews the API returns.
  • Folding suggestions. ReleaseService computes them from stored data alone while the release is IN_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 which ChangeFoldingService.confirmedDuplicates pairs with one. A suggestion with a row in release_fold_decisions is 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.review by the person, and a release_change_reviews row EDIT with folded_change_id; refused for an Unknown code change), removes the tracker change from the release, excludes it through ChangeExclusionService when 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 AudienceReleaseNote per 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 with 409 release_note_render_failed. Before that, ReleaseNotePreview.needsSummary finds every change whose title, without its Conventional Commit prefix, issue keys, and #n or !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 answers 409 change_summary_required naming 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.Narrative binds narratives[<code>].relevance, .headline, and .body from 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_narratives holds one AudienceNarrative object per audience code; Flyway V32 rewrote each string stored before as {"relevance": "FULL", "headline": "", "body": <string>}. ChangeView returns them as audienceNarrativeDetails, and keeps audienceNarratives as 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. ChangeClassifier sets security for a label equal, ignoring case and surrounding whitespace, to security, security-fix, security fix, or vulnerability, and for CVE-\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, like breaking_change. ChangeAiMerge stores 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 V34 adds changes.security (false for every change recorded before) and redefines changes_review_required so a security change leaves review only with a recorded review.
  • Releases. upgrade_guide_url is checked by ReleaseLinkBuilder.validatedUpgradeGuideUrl (400 invalid_upgrade_guide_url), and previous_release_id must be a published release of the same Project (400 invalid_previous_release), which the composite foreign key and the releases_previous_release_published trigger hold in the database too. ReleaseRequest records whether each field was sent, so an older caller's update keeps both and a create without previousReleaseId takes the Project's most recently published release by published_at. The pages always send both.
  • Footers. An audience and each language variant have a footer_template_body; AudienceTemplate.validateFooter compiles and renders it with ReleaseLinks.SAMPLE, under the same compiler, with the template_invalid contract 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 a FooterValue: 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, resetToPreset restores them in every language, and V34 gave existing operator and contributor audiences the same text (a migration test compares them). Approval snapshots the footer into footer_template_snapshot; notes written before have a blank one.
  • Links. ReleaseLinkBuilder reads the Project's sources from the database and keeps GitHub and GitLab ones; with exactly one, it builds compareUrl from the previous release's version and this one's, and releaseUrl from this one's, each a path segment encoded by UriUtils and used as the tag name exactly as written. It makes no provider call, so rendering a note, a preview included, never touches the network. ReleaseNoteDigest escapes 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 (package audience) stores the Organization's 1–5 target languages in organization_translation_settings, canonicalized by OutputLanguage.parse. Without a row, the output language is the only one.
  • Templates. audience_template_variants holds 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 translation package depends on no other domain package but project, for the Project's context (ADR-0035). TranslationService.ensure touches 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, and input_hash (SHA-256 of the source language, the texts sorted by key, and the Project's context when there is one), and otherwise creates a translation_jobs row that keeps that context (translation_jobs.context, Flyway V30): SUCCEEDED when every text is in translation_cache, FAILED (translation_disabled) without a provider, and PENDING otherwise.
  • Worker. TranslationWorker runs every second. It claims one due job with FOR 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, to DeepLTranslator outside any transaction: POST /v2/translate with DeepL-Auth-Key, the job's context as context when 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 with min(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 publishes TranslationFinished; a RUNNING job left for ten minutes becomes PENDING again.
  • Notes. ReleaseNoteWriter localizes the release's changes for one language: a summarized change in another language is replaced by ChangeView.withContent with its translated summary and narratives once ready, and keeps its own text otherwise. A narrative's body and headline are the texts narrative.<code> and headline.<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 through TranslationService.ensureForRelease, a job whose release_id is 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 (FAILED over PENDING over READY) in release_audience_notes.translation_status. Approval writes a note per target language and audience from templateFor; ReleaseService listens to TranslationFinished in 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. retryTranslations restarts the failed jobs of an approved release's current texts. Editing a note by hand makes it READY.
  • 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, so translation still depends on no domain package but project. GlossaryService keeps kept terms and fixed translations (glossary_kept_terms, glossary_translations, Flyway V33) 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, and TranslationTexts.inputHash and textHash add it beside the context only when it is not empty, so an Organization without a glossary hashes as before. ensure records the version on the job and, while the job is pending, sets the pair's glossary_syncs row to want it, locked and inserted with ON CONFLICT DO NOTHING. lockNextDue skips a job whose pair is PENDING or RUNNING for its version. GlossarySyncWorker claims a due row with SKIP LOCKED, only while no other pair of the Organization is RUNNING, under the lock of translation_glossaries, and outside any transaction asks GET /v3/languages?resource=glossary (a pair is supported when both languages are listed; features is not read), then POST /v3/glossaries or PUT /v3/glossaries/{id}/dictionaries, creating the glossary again on a 404. 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 sends glossary_id only when the row is SYNCED at 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. A 400 with a glossary sends the dictionary again and retries. UntranslatedGuard checks 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 with untranslated and is never cached. TranslationJob.succeed then passes each text of its output, from DeepL or the cache, through SourceForms.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.unpairedSpans reports 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. ReleaseNoteWriter combines the jobs' outcomes per language (NOT_APPLIED over PENDING over APPLIED over NONE) into release_audience_notes.glossary_status, and ReleaseView.glossaries reports it per language. retryTranslations also 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. publish refuses a release with a note that is not ready (409 translations_not_ready), and the releases_publish_ready_notes trigger 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 translationPoll Alpine 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. AutomationRunFactory records 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 as github_source_disconnected before any call, and a retry after the reconnect succeeds. A rule view carries gitHubSourceMissing while 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 MarkdownHtml into 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 beneath atlassian.net over 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 to FAILED, a 5xx or a lost connection to UNKNOWN, and a redirect to FAILED, 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: TeamsText drops 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 MarkdownHtml output, bounded at 1,000,000 bytes. Because nothing is published until the second call, every way the first can fail is FAILED — including a 5xx — while the second follows the usual rule, and a 2xx naming no article is UNKNOWN.

See ADR-0024 and ADR-0025.

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.parse and by a CHECK constraint. V24 gives every Organization one made from its name, numbering collisions by age; registration derives one the same way. PUT /api/organization/slug and the card on /projects move it, which is an administrator's decision because links already shared stop working.
  • An entry is written only by a PUBLIC_CHANGELOG action, 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 as release_notes does.
  • 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. PublicChangelogController serves GET /changelog/{slug} (public, max-age=300), GET /changelog/{slug}/releases/{entryId} (public, max-age=86400, immutable, with the entry's identifier as its ETag and 304 for a reader who has it), and GET /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 is 404, and an Organization with nothing published looks the same as one that does not exist.
  • The list groups languages. PublicChangelogService.findFeed turns the 50 newest entries into one card per release and audience, holding each language in publication order and named by EntryView.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 RSS description carries that HTML, escaped into the document by the JDK's XML writer.
  • Links come from configuration. releaseflow.public.base-url is where this deployment is reached; releaseflow.public.changelog-base-domain, when set, serves each Organization at {slug}.{domain} through PublicChangelogHostRoutingFilter, which rewrites exactly three paths for exactly one label, for GET only, before Spring Security sees the request. A Host header 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):

OrderMatchesAllowsCSRFSession
0Actuator endpoints, matched with EndpointRequest.toAnyEndpoint() on the management portGET health and Prometheus; everything else deniedExempted for these endpoints only: a scrape carries no cookie and could never send a tokenNone
1/webhooks/**POST to the GitHub, GitLab, Linear, and automation webhooks, and the signed GET of an automation run; everything else deniedExempted with ignoringRequestMatchers("/webhooks/**"): every request is proven by an HMAC over itself and reads no cookieNone
2/changelog/**GET onlyNothing exempted; the methods a token guards are deniedNone, and no request cache
3Everything elsePublic pages, registration, sign-in, invitations, and static files; the rest needs a session, and the administrator paths listed under Roles and invitations need an administratorRequired for every write, REST includedServer-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 marked internal: true, and never publishes the port. A security chain of its own, matched with EndpointRequest.toAnyEndpoint() rather than by path, permits GET on health and Prometheus, denies the rest, and creates no session. The application port serves none of it.
  • Four metrics, all labels from finite sets. ClassificationMetrics owns the count of committed classifications by needs_human_review, the timer from a change arriving to its classification, and provider requests by provider and outcome; AutomationMetrics owns deliveries by trigger and outcome. 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 unknown when recovery marks it so. FAILED and UNKNOWN stay apart: an unconfirmed delivery may have arrived.
  • One decorator counts every provider request. MeteredChangeClassifier wraps 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.