skip to content

In the Pact Broker, what is the difference between a branch, a tag and an environment?

level: middleimportance: should knowfreq 47%

answer

  1. Three labels, three different lifetimes
  2. One is provenance, one is state
  3. Only one is a first-class object
  4. Deployments are recorded, not tagged
  5. Branch drives selection, environment drives gating

basics

~20 s

A branch is a property set on an application version when its pact is published, mirroring the git branch. A tag is a movable label on a version. An environment is a first-class object you record deployments and releases against.

solid answer

~50 s

All three attach to a pacticipant version in the Pact Broker, but they answer different questions and live for different lengths of time. A **branch** is set at publish time (`--branch`) and records where the code came from; it is effectively fixed for that version and is what provider selectors use to pick which pacts to verify — for example the main branch, or the branch matching the provider's own. A **tag** is a free-form label you attach to a version and can move to another version whenever you like; it predates the other two and was historically overloaded to mean both branch and environment. An **environment** is not a label at all: you create it in the broker, then record a deployment or a release of a version *to* it. That record is mutable state — the broker's belief about what is currently running there — and it is what `can-i-deploy --to-environment` reads.

code

bash · 8 lines
bash
# once, when the environment first exists
pact-broker create-environment --name production --production

# after each successful deploy of that exact version
pact-broker record-deployment \
  --pacticipant depot-scheduler \
  --version 3f9a1c2 \
  --environment production

go deeper

for a junior

Recall that the Pact Broker keeps more than the contract file: it also records where a version came from and where it has been deployed, and those are separate pieces of information.

for a middle

Be ready to define branch, tag and environment in broker terms and to say which one a deployability check consults — and to explain why a deployment is recorded rather than tagged.

for a senior

An interviewer expects you to connect the choice to failure modes: an unrecorded deployment makes environment answers stale, and a mis-branded feature-branch pact makes an unmerged expectation look like the main line's.

for a principal

Own the migration story for an organisation still using tags for everything, and decide how strictly deployment recording is enforced so that the broker's view of reality stays trustworthy.

## Three labels, three questions The Pact Broker attaches metadata to a pacticipant version, and three kinds of metadata are constantly confused because in ordinary English they all sound like "a label". They are not interchangeable, and picking the wrong one silently weakens every later check. **Branch** answers *where did this code come from?* You set it when you publish, with `--branch` on `pact-broker publish`, and it normally mirrors the git branch of the build. It belongs to the version and you do not move it around afterwards. Its job is selection: when a provider verifies, it asks the broker for a set of pacts, and "the pacts from the consumer's main branch" or "the pacts from a branch with the same name as mine" are branch-driven queries. **Tag** answers *what did someone decide to call this version?* It is an arbitrary string you can attach to a version at publish time with `--tag`, and you can attach the same tag to a different version later. Tags are the oldest of the three mechanisms and were pressed into service for everything: `prod` as an environment, `main` as a branch, `feat-x` as a work marker. That overloading is precisely why the broker later grew first-class branches and environments. Tags still work and still appear in older pipelines, but a tag has no meaning the broker understands beyond "this string is on this version". **Environment** answers *what is running where, right now?* It is a first-class object you create in the broker before you can use it, with a name and a flag marking it as production or not. You never tag a version with an environment. Instead you record that a version was **deployed** to it, or **released** into it, and the broker maintains the resulting current-state view: recording a newer version of the same application as deployed replaces the previous one, and there is an explicit undeployment operation for taking one out without putting another in. ## Lifetimes, side by side | Concept | Set how | Mutable? | Lifetime | Read by | |---|---|---|---|---| | Branch | `--branch` at publish | Effectively fixed for that version | As long as the version record | Provider consumer-version selectors | | Tag | `--tag` at publish | Yes — you move it | Whatever you make it | Older selectors and `can-i-deploy --to` | | Environment | Created once, then deployment/release records | Yes — it is current state | Until a newer version is recorded there | `can-i-deploy --to-environment` | The row that matters most is the last one. A deployability check aimed at an environment is not reading a label at all; it is reading the broker's record of which versions are currently deployed or released there, and then asking whether your candidate version is compatible with exactly those. That is why a team that publishes diligently but never records deployments gets confident answers about a world that does not exist. ## Why the distinction bites 1. **Selection versus state.** Branches decide *what a provider bothers to verify*. Environments decide *what a release is checked against*. Using a tag for both, the old way, means one string is doing two jobs and neither is reliable when they disagree. 2. **Feature branches.** Publishing a feature branch's pact with its branch name lets the provider verify it without that expectation being treated as the main line's requirement. Tag it `main` instead and you have told the whole organisation that the unmerged expectation is the truth. 3. **Multi-instance environments.** A depot system might run the same scheduler in several depots. Deployment records support an application-instance notion so the broker can hold more than one current version in one environment, which a flat tag cannot express. 4. **Deployment versus release.** These are two different verbs on an environment. Recording a *deployment* models the case where a new version replaces the old one — a service. Recording a *release* models the case where a version becomes available without displacing its predecessor — a mobile app or a library, where several released versions coexist and are supported until support ends. ## What to do on a new pipeline - Publish every consumer build with `--consumer-app-version` set to the commit sha and `--branch` set to the git branch. - Create the environments you actually deploy to once, up front, and mark the production ones as such. - Make the same automation that performs a deployment record it in the broker immediately afterwards, so the broker's current-state view cannot drift from reality. - Reach for tags only when you are maintaining an older pipeline that already depends on them; do not introduce new meanings on top of them. Held apart like this, the three answer cleanly: branch is provenance, tag is a bookmark, environment is state.

  • What does the Pact Broker's record-release capture that record-deployment does not?
    A deployment models replacement: recording a new version as deployed to an environment means the previous one is no longer there. A release models availability without displacement — several released versions of a mobile app or a library coexist in the same environment, each staying current until its support is explicitly ended. Use deployment for services, release where old versions remain in use.
  • A version's pact was published from a feature branch. Why does the branch value change what providers verify?
    Providers do not fetch every pact in the broker; they fetch a selected set. Selectors are expressed in terms of branches — the consumer's main branch, or a branch matching the provider's own — so a correctly branded feature-branch version is available for opt-in verification without being treated as the main line's requirement.

saying these in an interview costs you the question

  • Treats a tag and an environment as the same thing
  • Tags a version 'prod' instead of recording a deployment
  • Thinks a branch is something you move between versions
  • Publishes feature-branch pacts under the main branch
  • Assumes the broker learns deployments from the pipeline automatically