Release Management

Release management workflow

Build-once, promote-everywhere release workflow covering versioning, changelog state, release orchestration, signing, docs deployment, and release evidence.

Maintainer workflow

Release Policy covers the public release cadence, channel rules, and stable release gates. The steps below cover the maintainer workflow once a release is being executed.

Diagram

Build once, promote everywhere

Release workflows build immutable artifacts first, then gate, sign, and publish by digest.

Decision matrix

Release channels

Release channels.

Channel	Trigger	What it publishes	Operational rule
Stable release	Merge the release-please PR so the Release Tag workflow can resolve the merged release PR, create the signed stable version tag, and create the draft GitHub Release from main or a release-* branch.	GitHub Release assets, OCI Helm chart, signed images, stable docs snapshot, docs deployment, and provenance evidence.	Stable releases become permanent release-line docs and own the default /docs route.
Patch release	Backport the targeted fixes to the relevant release-* branch, then use the Prepare Release-As PR workflow to create the auditable Release-As: X.Y.Z marker PR.	Same release artifacts as stable releases, built from the patch branch tag.	Keep the patch branch narrow; patch releases in an existing stable line reuse that line's docs snapshot.
Prerelease	Prefer the Prepare Release-As PR workflow to create a tiny PR that carries an empty commit with Release-As: 0.1.0-rc.6, then merge the resulting release-please PR so the Release Tag workflow creates the signed prerelease tag and draft GitHub Release.	GitHub Release assets, OCI Helm chart, signed images, docs site deployment, and provenance evidence.	Prereleases use /docs/next plus release notes; do not create a permanent versioned docs snapshot.
Edge	CI success on main.	Mutable and immutable edge manifests plus signed images and provenance metadata.	Pre-release validation channel; production support expectations remain with stable releases.
Nightly	Nightly validation success.	Nightly manifests, tags, and provenance metadata.	Scheduled validation and drift-detection channel; stable releases remain the publication path.

Stable release-line docs snapshots

Before merging the first stable X.Y.0 release PR for a release line, snapshot the docs for that release line and commit the generated artifacts. Patch releases in the same line reuse the X.Y.0 docs version, but user-facing docs fixes for that patch must refresh the existing X.Y.0 snapshot from the release branch. Prereleases continue to use /docs/next and release notes only; do not add patch, -alpha, -beta, or -rc entries to website/versions.json.

Patch branch workflow state

GitHub Actions runs workflow definitions from the branch that receives the push. Before using release-please on an older release-* branch for the first time, make sure the branch contains the current release workflow support, including Release Please PR, Release Tag, and Prepare Release-As PR behavior.

Configure

Snapshot docs for the stable release line

bash

make docs-version DOCS_VERSION=X.Y.0

This updates website/versioned_docs/, website/versioned_sidebars/, and website/versions.json.

Configure

Refresh docs for a patch release line

bash

git switch release-X.Y
make docs-refresh-version DOCS_VERSION=X.Y.0

Run this from the release branch after backporting docs that apply to the patch release. This updates the existing release-line docs snapshot without adding a patch version to website/versions.json.

Configure

Cut an explicit release with a Release-As PR

bash

# In GitHub Actions, run:
# Prepare Release-As PR
#
# target_branch: main        # or release-0.2
# version: 0.1.0-rc.6       # or 0.2.1

This workflow creates a tiny PR containing an empty Release-As: <version> commit. Merge that marker PR first; the branch-aware Release Please workflow then opens or updates the real release PR.

`workflow_dispatch` `release_as` path

Release Please PR still exposes a workflow_dispatch release_as input, but maintainers should prefer the Prepare Release-As PR workflow. The marker PR leaves the version override in git history and works consistently for main and release-* branches.

Helm chart changelog

Release-please remains the source of truth for release notes. After release-please opens or updates a release PR, the Release Please PR workflow syncs charts/openbao-operator/Chart.yaml so Artifact Hub receives artifacthub.io/changes, image metadata, prerelease state, and security-update state from the release-please changelog.

Human release notes

Keep CHANGELOG.md generated by release-please. Put hand-written release summaries, migration notes, and operator-facing callouts in release-notes/X.Y.Z.md; the website release generator and draft GitHub Release creation prepend that file to the generated changelog entry for the matching version.

For patch releases, make the source that release-please sees match the release note you want. Prefer one cherry-picked conventional commit per user-facing fix. If a backport PR is squash-merged, make the squash title deliberately user-facing because it becomes the generated changelog entry. Use release-notes/X.Y.Z.md for extra context, but do not hand-edit generated CHANGELOG.md sections.

Decision matrix

Release manager checklist

Release manager checklist.

Stage	What to prove before moving on
Pre-flight	Release-please PR looks correct, docs are updated, new stable release lines have a committed X.Y.0 docs snapshot, compatibility docs are current, CI is green, full E2E release evidence is clean, nightly regressions are reviewed, and performance findings are either cleared or explicitly accepted by maintainers.
Publish	Release workflow passes the release-publish environment gate, then tags, signs, attests, publishes assets, and keeps chart/app versions aligned with the git tag.
Post-release	GitHub Release exists, assets verify, provenance evidence is recorded, Artifact Hub metadata is visible, no unexpected release-please PR or branch remains, and announcement links are captured.

Verify

Run post-release verification

bash

VERSION=X.Y.Z REPO=dc-tec/openbao-operator hack/ci/verify-post-release.sh

Requires gh, jq, git, Docker Buildx, and cosign. Checks the remote tag, published GitHub Release assets, checksum signature, OCI Helm chart publication and signature, and leftover release-please PRs or branches.

Verify

Post-release verification skeleton

bash

IMAGE="ghcr.io/dc-tec/openbao-operator@sha256:<digest>"
CHART="ghcr.io/dc-tec/charts/openbao-operator@sha256:<digest>"

cosign verify \
--new-bundle-format=true \
--certificate-identity "https://github.com/dc-tec/openbao-operator/.github/workflows/release.yml@refs/tags/X.Y.Z" \
--certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
"${IMAGE}"

gh attestation verify "oci://${CHART}" \
--repo dc-tec/openbao-operator \
--signer-workflow dc-tec/openbao-operator/.github/workflows/release.yml \
--source-ref refs/tags/X.Y.Z \
--cert-oidc-issuer https://token.actions.githubusercontent.com \
--deny-self-hosted-runners

jq '.release, .identity_constraints, .images, .chart, .release_artifacts.checksums_txt' provenance-index.json

Verify images, charts, checksums, and the provenance index against the exact tag and workflow identity used for the release.

Verifying artifacts

Run hack/ci/verify-post-release.sh first and use the verification skeleton above for deeper spot checks or release evidence capture. Keep the exact workflow identity, tag ref, and digest-pinned subjects aligned with the artifacts that were just published. Once the release is fully published, delete the matching release-please--branches--<base> branch unless release-please still has an active release PR for that base branch.

release-please token requirements

Release automation must use non-default tokens so the resulting tag and GitHub Release can trigger downstream workflows. Use two repo-scoped GitHub Apps:

• OPENBAO_OPERATOR_RELEASE_PR_CLIENT_ID and OPENBAO_OPERATOR_RELEASE_PR_PRIVATE_KEY for PR-only release-please
• OPENBAO_OPERATOR_RELEASE_TAG_CLIENT_ID and OPENBAO_OPERATOR_RELEASE_TAG_PRIVATE_KEY for the custom Release Tag workflow

The tag app should be the only actor with semver tag ruleset bypass, and it only needs repository contents: write.

Signed release tags also require these repo secrets:

• OPENBAO_OPERATOR_RELEASE_TAG_GPG_PRIVATE_KEY - armored private key for the dedicated release-signing identity
• OPENBAO_OPERATOR_RELEASE_TAG_GPG_PASSPHRASE - passphrase for that private key
• OPENBAO_OPERATOR_RELEASE_TAG_GPG_NAME - tagger name to write into signed release tags
• OPENBAO_OPERATOR_RELEASE_TAG_GPG_EMAIL - tagger email to write into signed release tags

Upload the matching public key to the GitHub identity that should show the Verified badge for release tags. Prefer a dedicated release-signing key instead of a day-to-day maintainer key. A PAT fallback is possible through RELEASE_PLEASE_TOKEN, but a bot identity is safer than a maintainer’s personal token.

After release execution

Release policyRelease policy covers cadence and release-gate rules.DistributionDistribution covers Artifact Hub metadata, chart publishing assumptions, and deferred OLM posture.Continuous integrationContinuous integration covers workflow behavior before publish.Project governanceProject governance covers SDLC and supply-chain policy changes.