Development workflow

The day-to-day cycle for changing Consul.

Branching

• Default branch: main. New work targets main.
• Release branches are named release/<minor>.x (e.g., release/1.22.x). They are managed by maintainers; backports flow in via labels rather than direct pushes.
• Tag scheme: v<major>.<minor>.<patch> (v1.22.7, v1.21.5, ...). The version on main is 2.0.0-dev (see version/VERSION), reflecting the in-progress v2 resource API direction.

Building locally

# Single-arch dev binary in ./bin/consul
make dev

# All platforms (CI does this)
make

# Linux binary cross-compiled for integration tests
make linux

# Local docker image (consul-dev:latest by default)
make dev-docker

The make dev target embeds the current short git SHA via -ldflags (version.GitCommit) and the build date via build-support/scripts/build-date.sh.

Running and iterating

# Single-node dev mode with everything wired up
./bin/consul agent -dev -ui

# Three-node local cluster (servers only) using the helper script
./bin/consul agent -server -bootstrap-expect=1 \
  -client=0.0.0.0 -bind=127.0.0.1 -data-dir=/tmp/consul-1
# (repeat for ports 8301/8302 etc., joining via `-retry-join`)

When iterating on agent code, restart the agent after each make dev. When iterating on the CLI, no restart is needed.

To exercise the v2 resource API locally:

./bin/consul resource list catalog.v2.Service
./bin/consul resource read catalog.v2.Service my-service

See command/resource/ and proto-public/pbresource/ for the full surface.

Submitting a PR

1. Push your branch to your fork.
2. Open the PR against hashicorp/consul:main. Link the issue.
3. Fill in the PR template — what changed, why, how it was tested.
4. Apply labels (see .github/CONTRIBUTING.md for the table).
5. Add a .changelog/<PR>.txt entry unless the change is invisible to operators.
6. Watch CI (GitHub Actions, see .github/workflows/). Most failures show up as make lint violations or flaky integration tests.

Continuous integration

CI is configured in .github/workflows/. Key workflows:

• build.yml — multi-platform binary builds.
• test.yml — unit tests for the root module and each sub-module.
• test-integrations.yml — Envoy/Connect integration suites.
• reusable-get-go-version.yml — pulls .go-version so all jobs use the same Go.
• lint.yml — golangci-lint per module.
• backport-assistant.yml — opens backport PRs when backport/* labels are set.

The actual matrix of OSes and architectures Consul ships on is in .release/.