Operations
Running ReleaseFlow, watching it, and installing a published version. Every variable is listed in Configuration.
Run with Docker Compose
docker-compose.demo.yml builds the application image from this checkout and runs
it with PostgreSQL 17, Prometheus, and Grafana for local evaluation; it is not a
production deployment. Run the demo stack shows
how to start it, and the Quickstart runs a released
version without building it.
Compose refuses to start until RELEASEFLOW_DB_PASSWORD,
RELEASEFLOW_CREDENTIAL_MASTER_KEY, and RELEASEFLOW_GRAFANA_PASSWORD are set.
The application listens on http://127.0.0.1:8080 (change it with
RELEASEFLOW_HTTP_PORT), the operations dashboard on http://127.0.0.1:3000
and Prometheus on http://127.0.0.1:9090. The database port and the
management port are not published. The container runs as UID 65534, and its
health check calls the management port.
docker compose -f docker-compose.demo.yml down --volumes removes the demo data.
Health and metrics
Actuator answers on its own port — 8081 on loopback by default, set with
RELEASEFLOW_MANAGEMENT_PORT and RELEASEFLOW_MANAGEMENT_ADDRESS — and serves
exactly two things there: GET /actuator/health, without component details, and
GET /actuator/prometheus. Everything else is refused, and the application port
serves none of it. Keep that port private; it is not a product endpoint.
Four metrics answer the operational questions, and every label comes from a finite set:
| Metric | Labels | What it answers |
|---|---|---|
releaseflow_classification_completed_total | needs_human_review | How much is classified, and how much of it still needs a person |
releaseflow_classification_collect_to_complete_seconds | — | How long a change waits between arriving and being classified |
releaseflow_classification_provider_requests_total | provider, outcome | How often the AI refuses or cannot be read |
releaseflow_automation_action_executions_total | trigger, outcome | How deliveries end, with unknown kept apart from failed |
No label ever carries an Organization, Project, release, rule, run, action, model, external reference, or error text. Metrics are a deployment-wide view; a question about one Organization is a product feature, not a label. Every series exists from startup at zero, so a panel reads zero rather than "no data".
The demo stack provisions a ReleaseFlow Operations dashboard in Grafana with seven panels: changes needing human review, classification throughput, time from a change arriving to its classification, AI provider error rate, action failure rate by trigger, deliveries nobody could confirm, and whether Prometheus can reach the application. Prometheus keeps seven days of history. Alerting, durable storage, a retention policy, and access control are a real deployment's own to bring. See ADR-0026.

Container image
The Dockerfile builds the JAR in a JDK stage and copies it into a Temurin 21 JRE image
that runs as UID/GID 65534; its health check calls the management port. Build it on
its own with docker build .. The image reads the same RELEASEFLOW_* environment
variables as ./mvnw spring-boot:run, and needs a PostgreSQL database it can reach.
Serve it behind HTTPS and set RELEASEFLOW_SESSION_COOKIE_SECURE=true and
RELEASEFLOW_PUBLIC_BASE_URL to the public address.
Deploying to production
The quickstart and the demo stack run on one machine for evaluation. A deployment other people rely on needs the following, and ReleaseFlow provides none of it itself.
HTTPS and a reverse proxy. Terminate TLS at a reverse proxy in front of the application port and set:
RELEASEFLOW_PUBLIC_BASE_URL=https://releaseflow.example.com
RELEASEFLOW_SESSION_COOKIE_SECURE=true
SERVER_FORWARD_HEADERS_STRATEGY=native
The last one is Spring Boot's own setting: it lets the application read the proxy's
X-Forwarded-Proto and X-Forwarded-Host. Without it, behind a proxy that terminates
TLS, a redirect such as the one to the sign-in page points at http://, and the
interface-language and remembered-Project cookies are not marked Secure. The embedded
Tomcat accepts these headers only from private and loopback addresses; a proxy anywhere
else is named with SERVER_TOMCAT_REMOTEIP_INTERNAL_PROXIES. Neither Compose file
forwards these variables, so add them to the app service's environment if you build
on one.
What the internet reaches. Providers need /webhooks/, and anonymous readers need
/changelog/ if you publish a public changelog. Your own people need the rest, which can
stay behind a VPN or an allowlist. Once your Organization exists, refuse /register and
POST /api/registrations at the proxy, because
registration stays open. Never route the management port
through the proxy.
Webhooks. ReleaseFlow has no inbound rate limit either: a webhook request is bounded
only by the 1 MiB body limit, checked first. A refused delivery to a known source's path
is counted on the source's page, coalesced to about one row update per source per second
however many arrive (ADR-0042), but each one
still costs a lookup and a signature check. If you expect floods, limit /webhooks/** at
the proxy.
Signing in. ReleaseFlow does not limit failed sign-in attempts, so rate-limit
POST /login at the proxy. Sessions live in the application's memory: a restart signs
everybody out.
One instance. The background workers claim their work with FOR UPDATE SKIP LOCKED
and are written to run in every instance
(ADR-0008), but sessions are not shared between
instances and nothing in CI runs more than one. Run a single instance unless you have
tested more behind sticky sessions.
The database. Every test and both Compose stacks run PostgreSQL 17. Give ReleaseFlow a database of its own, owned by the user it connects as: Flyway creates the tables, constraints, and triggers when the application starts.
Backups. Back up the database and RELEASEFLOW_CREDENTIAL_MASTER_KEY together, and
store them apart. A database restored without its key still starts, but every stored
secret is unreadable. Access tokens and action secrets can be entered again. A source's
webhook secret is refused at every delivery with 401 webhook_signature_invalid, and the
log says Could not decrypt the webhook secret of source …, until it is
rotated and the new one given to the provider. Restore a whole dump into an empty
database:
pg_dump --format=custom --file=releaseflow.dump releaseflow
createdb restored && pg_restore --dbname=restored --no-owner releaseflow.dump
pg_restore creates the triggers that freeze published releases after it has loaded the
data. Restoring the data alone into a database the application has already migrated is
refused by those triggers for every release past its draft.
Upgrades. A newer version migrates the schema forward when it starts, and no migration can be undone. Take a backup first; going back means restoring that backup with the older version, never starting the older version against the migrated database.
Upgrading with a reasoning model
From 1.1.0 every classification request asks for the same temperature, 0 unless
RELEASEFLOW_AI_TEMPERATURE names another
(ADR-0035,
ADR-0038); 1.0 sent none. A model that accepts
only its default temperature refuses a request that names one: OpenAI's reasoning models do,
and so did Claude models released after Opus 4.6 until Anthropic requests stopped carrying a
temperature (see Upgrading with Anthropic).
No action is needed. When the provider refuses the temperature, ReleaseFlow sends the same request once more without it, and leaves it out of every later request until it restarts (ADR-0039). The log says so once:
OpenAI model o4-mini refused the temperature, so classification requests leave it out until ReleaseFlow restarts. Set RELEASEFLOW_AI_TEMPERATURE=default to avoid the first refusal.
Each start costs one refused request. To skip it, set:
RELEASEFLOW_AI_TEMPERATURE=default
Requests then leave the temperature out from the first, as every request did before. With
Docker Compose, put it in the .env beside the Compose file, which forwards it and sends 0
when it is not set. A deployment whose model accepts a temperature sends 0 and sees no
refusal.
Upgrading with Anthropic
From 1.3.0 ReleaseFlow calls Claude with Anthropic API version 2026-10-21, which takes no
temperature (ADR-0045). For a deployment
with RELEASEFLOW_AI_PROVIDER=anthropic:
-
No setting needs to change. Requests carry no temperature, whatever
RELEASEFLOW_AI_TEMPERATUREsays. A number other than0logs one warning at startup and can be removed:textRELEASEFLOW_AI_TEMPERATURE is ignored for anthropic: Anthropic API version 2026-10-21 takes no temperature, so Claude samples with its default. Remove the setting to silence this warning. -
On Claude 4.7 and later, classification samples as before. The first request after each start is no longer refused for its temperature, so its warning goes away.
-
On Claude 4.6 and earlier (such as Sonnet 4.6, Opus 4.6, or Haiku 4.5), classification runs at the model's default temperature,
1.0, instead of0, so notes vary more between runs than on 1.2: a change classified again may be worded differently, or, where its evidence is thin, get another category. No setting brings0back on Anthropic; OpenAI and DeepSeek still take it. Rules, mandatory review, and one request per change are unchanged. -
The API key is sent as
Authorization: Bearer <key>instead ofx-api-key, withanthropic-version: 2026-10-21. A proxy or gateway atRELEASEFLOW_ANTHROPIC_BASE_URLthat reads or setsx-api-key, or checksanthropic-version, must accept these before the upgrade; one that forwards to Amazon Bedrock accepts2026-10-21only for Claude 4.7 and later. The Claude API itself accepts either header.
The Anthropic SDK inside the JAR and the image is now under the Apache License 2.0 instead of
MIT. It ships no NOTICE file, and its licence files stay inside its jars.
Upgrading to the glossary
The version that adds the glossary (Flyway V33) changes
nothing until an administrator adds a term: an Organization without one sends DeepL the
same requests as before, and no note is translated again. To keep terms after upgrading:
- Open Glossary, tick the suggested terms your readers keep in English, and keep any others, one per entry as they should appear. Add a fixed translation for a term that should always become the same words in one language.
- Return an approved release to draft and approve it again, or approve the next one: translations made from then on use the glossary. Published notes never change.
- Check the release page: each language says whether the glossary was Sent with every
translation. That means DeepL received it, not that every term was kept, so read the
notes, and add a phrase DeepL translated, such as
container images, as its own kept term.
On DeepL API Free, one Organization gets the glossary. ReleaseFlow uses one DeepL
glossary per Organization, and an API Free account holds only as many as its plan allows:
one, when this was tested. The first Organization to sync uses it; every other
Organization's sync fails with quota_exceeded and its notes are translated without a
glossary, which its release page and Glossary page say. A deployment that serves several
Organizations with glossaries needs a DeepL plan that holds that many. A glossary created
in the account by anything else takes a slot too.
Published artifacts
ReleaseFlow's own releases, as opposed to the ones it writes notes for, listed on the
Releases page. This
section describes what the Release workflow publishes for each tag.
A release is a tag, and the tag is the version: pom.xml holds only the
0.0.0-SNAPSHOT placeholder in ${revision}, and the Release workflow builds the tagged commit with -Drevision=<version>.
Pushing v<version> runs that workflow, which refuses a tag that is not an
ancestor of main, or one that CHANGELOG.md has no dated entry for — so a
mistaken tag fails rather than ships. It then runs the whole suite again, checks
the JAR carries the version, builds and scans the image, and publishes:
releaseflow-<version>.jar, the executable JAR;releaseflow-<version>-sbom.cdx.json, a CycloneDX SBOM of the image, which lists the Java dependencies and the base image's packages together;compose.yamlandquickstart.sh, the Quickstart bundle, with the image pinned to the digest this release pushed;SHA256SUMS,LICENSEandNOTICE;- the image on GHCR, tagged
<version>,<major>.<minor>,<major>andlatest; - a provenance attestation for the image, the JAR, and the quickstart bundle;
- a GitHub release whose notes are the version's
CHANGELOG.mdentry, followed by the image digest, the quickstart commands, and how to verify the downloads.
A v<version>-rc.<n> tag on release/<version> or hotfix/<version> publishes a
release candidate the same way, marked as a pre-release, with the image tagged only
<version>-rc.<n> so nothing that follows latest moves to it. The workflow can also
be started by hand for a tag that already exists.
To cut a release, see Releasing: two commands,
scripts/release.sh start <version> and, once its pull request is merged,
scripts/release.sh finish <version>.
Check what you downloaded:
sha256sum --check SHA256SUMS
gh attestation verify releaseflow-<version>.jar \
--repo hoangluongtran0309/ReleaseFlow
Pin a deployment to the digest rather than to a moving tag:
docker pull ghcr.io/hoangluongtran0309/releaseflow@sha256:<digest>