Release Branch Management#

Vault maintains multiple active release branches simultaneously using a label-driven backport system backed by a custom Go pipeline CLI. The key components are:

• release/X.Y.x branches — tracked release lines for each active minor version
• backport/X.Y.x labels — applied to merged PRs to trigger automated backport PR creation
• pipeline github create backport — the CLI command that executes the backport logic, including CE/Enterprise file filtering
• .release/versions.hcl — the source of truth for which versions are active, LTS, and have active CE counterparts

Active Version Tracking#

.release/versions.hcl is the authoritative manifest for active release branches. As of the current state of the repo, the following versions are defined 1:

main is always implicitly active. Any version absent from this file is treated as inactive 2. The CI pipeline configuration in .release/ci.hcl registers main and release/** as the official release branches.

Label-Based Backporting#

The backport workflow is triggered by applying a backport/X.Y.x label to a merged PR (e.g., backport/1.20.x). The PR template reminds HashiCorp employees to apply the right labels and specifies that all available enterprise labels must be used for critical security or severity-1 bug fixes that need to reach current LTS versions.

On merge, the pipeline CLI (invoked via GitHub Actions) calls pipeline github create backport <PR-number>, which:

1. Reads the PR's backport labels to determine target branches 3
2. Determines whether the PR base is an enterprise or CE branch to decide which counterpart branches also need backporting 4
3. Cherry-picks the merge commit into each target branch and opens a backport PR titled "Backport of [description] into release/X.Y.x" 5
4. Posts a comment on the original PR summarizing each backport attempt and its status 6

If an automatic cherry-pick fails due to conflicts, the generated PR includes conflict-resolution instructions for a human to resolve manually 7.

CE/Enterprise File Filtering#

Enterprise branches automatically get a corresponding CE backport. When creating these CE backports, the pipeline tool strips out all enterprise-only files using the file groupings defined in .release/pipeline.hcl.

The enterprise file group — the most important grouping in the repo 8 — matches:

• Go files with _ent.go or _ent_test.go suffixes 9
• The entire vault_ent/ directory and other enterprise-only directories 10
• Config/workflow/doc files containing -ent, _ent, hsm, or merkle-tree patterns 11

The --ce-exclude-groups flag (default: "enterprise") controls which file groups are stripped. If a PR touches only enterprise files, the CE backport is skipped entirely. If a PR touches both enterprise and non-enterprise files, the CE backport is created with enterprise files removed 12.

Inactive CE branches receive backports only for docs, pipeline, and README changes 13. The --ce-allow-inactive-groups flag controls which file groups are allowed through to inactive CE branches.

Key Files and Entry Points#