Development workflow

The minimal day-to-day loop is make dev && bin/vault server -dev plus go test for the package you're touching. This page lists the targets, branches, and commit conventions you'll use along the way.

Branches

• main — current development. The next minor release cuts off this branch.
• release/<major>.<minor> — long-lived support branches (release/1.21, release/2.0.x, …). Backports merge here via the Vault Automation bot.
• release/<major>.<minor>+ent — the Enterprise sibling branches (closed-source).

When fixing a bug, target main. The maintainers and bot will cherry-pick to the active release branches.

Make targets

Makefile is the canonical entry point. Frequently used targets:

Target	What it does
make bootstrap	Installs build/lint tools listed in tools/.
make dev	Builds bin/vault (development binary, no UI).
make static-dist dev-ui	Builds the UI under ui/ and embeds it.
make fmt / make fmtcheck	Apply / verify gofmt + goimports.
make lint	Run golangci-lint with .golangci.yml.
make proto / make proto-lint	Regenerate / check *.proto files.
make test	Race-enabled unit tests across ./... (Docker required).
make testacc TEST=./builtin/logical/...	Acceptance tests for one backend.
make ember-dist	Build the UI without running the server.

Run make with no args to see the help text.

Commit and changelog

Each PR includes a file under changelog/<PR_ID>.txt. Example:

release-note:bug
core: fix race when standby nodes initialize quotas before storage is ready

The categories are security, change, feature, improvement, bug. The core: component prefix mirrors the entries in CHANGELOG.md. The file is consumed by HashiCorp's changelog-builder at release time.

Building a custom binary for local testing

For Enos and Docker tests, VAULT_BINARY lets you point the test cluster at a binary you just built:

GOOS=linux make dev
VAULT_BINARY=$(pwd)/bin/vault \
    go test -run 'TestRaft_Configuration_Docker' ./vault/external_tests/raft/raft_binary

README.md has more examples, including how to use hashicorp/vault or hashicorp/vault-enterprise Docker images for cluster tests.

Where to put new code

Kind of change	Lives in
New CLI subcommand	command/<verb>_<noun>.go, registered in command/commands.go
New audit device	audit/backend_<name>.go and registered in command/commands_full.go
New auth method	builtin/credential/<name>/ (built-in) or its own vault-plugin-auth-* repo
New secret engine	builtin/logical/<name>/ (built-in) or its own vault-plugin-secrets-* repo
New database plugin	plugins/database/<name>/
New storage backend	physical/<name>/ and registered in command/commands.go
New service registration backend	serviceregistration/<name>/
New sys/ API endpoint	vault/logical_system.go and helpers
New configuration block	command/server/config.go and internalshared/configutil/

Running with Enterprise stubs

If you see references to entExtend..., entAdd..., _ce.go, or _oss.go, those are the seams between OSS and Enterprise. The OSS file is a stub; Enterprise builds a parallel _ent.go file that's not in this repo. Don't try to delete the stubs — Enterprise builds depend on them being present.

Hooks

.hooks/ carries Git hooks for the team's local setup. Install them with:

git config core.hooksPath .hooks

The pre-commit hook runs gofmt, goimports, and the copywrite check.