Skip to main content

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:

MetricLabelsWhat it answers
releaseflow_classification_completed_totalneeds_human_reviewHow 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_totalprovider, outcomeHow often the AI refuses or cannot be read
releaseflow_automation_action_executions_totaltrigger, outcomeHow 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.

The ReleaseFlow Operations dashboard in Grafana, over 24 hours

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:

bash
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:

bash
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:

text
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:

bash
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_TEMPERATURE says. A number other than 0 logs one warning at startup and can be removed:

    text
    RELEASEFLOW_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 of 0, 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 brings 0 back 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 of x-api-key, with anthropic-version: 2026-10-21. A proxy or gateway at RELEASEFLOW_ANTHROPIC_BASE_URL that reads or sets x-api-key, or checks anthropic-version, must accept these before the upgrade; one that forwards to Amazon Bedrock accepts 2026-10-21 only 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:

  1. 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.
  2. 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.
  3. 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.yaml and quickstart.sh, the Quickstart bundle, with the image pinned to the digest this release pushed;
  • SHA256SUMS, LICENSE and NOTICE;
  • the image on GHCR, tagged <version>, <major>.<minor>, <major> and latest;
  • a provenance attestation for the image, the JAR, and the quickstart bundle;
  • a GitHub release whose notes are the version's CHANGELOG.md entry, 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:

bash
sha256sum --check SHA256SUMS
gh attestation verify releaseflow-<version>.jar \
--repo hoangluongtran0309/ReleaseFlow

Pin a deployment to the digest rather than to a moving tag:

bash
docker pull ghcr.io/hoangluongtran0309/releaseflow@sha256:<digest>