Skip to content

Releases

Cut one versioned release across every release-tracked repo: gate it, branch it, ship it and tag it.

Where
ReleasesIn the app (sign-in required), opens in a new tab.
Reading time
2 min read

How it works

A release ships a chosen set of repositories together, under one version. Which repos are in it is a setting (Releases → Settings); a repo nobody added is not released.

Three branches carry a release, and all three are read from your organization's git flow rather than named here, source is the flow's first stage, production its last, and the gate is the stage immediately before production. A flow with fewer than three stages has no distinct gate, so the gate collapses onto the source and the check passes trivially. A single-stage flow cannot release at all, and says so.

Creating one runs in order:

  1. Gate. For every tracked repo, the source branch must be fully merged into the gate branch. If one is not, the release is blocked and named, you run that promotion first.
  2. Cut. release/<version> is branched from the source in each repo.
  3. Record. The commits that are actually shipping (source beyond production) are written into the changelog. A commit lands even where a repo has no changes, so the protocol is uniform.
  4. Ship. The release branch is merged into production.
  5. Tag. The release branch is tagged v<version>.

It runs entirely through your own provider token, no container is involved.

Steps

Following along? Tick each number off as you go.

  1. Open Releases and choose the Settings tab.

  2. Add the repositories this organization releases together.

    Nothing can be released until at least one repo is tracked.

  3. Go back to the Releases tab and read the gate.

    Each repo says whether its source branch has reached the gate branch, and what would ship.

  4. Clear anything blocking the gate by promoting it first.

    Create release refuses while a repo is behind, and names it.

  5. Press Create release.

  6. Press Confirm approved & release to prod to ship the approved repos.

    Each is merged into production and tagged v<version>.

  7. Use Show commits in this release on a past release to see exactly what shipped.

    Resume any pending/failed repos picks up one that did not finish.

Worth knowing

  • The changelog commits DevBench writes are excluded from "what is shipping", so a release never reads as shipping its own changelog.

  • A blocked gate is not a failure, it is the release train telling you a promotion is still outstanding.

Read next

Code and shippingMerge requestsAn agent opens them, a person lands them, with the whole history kept, and a way to undo one that has already landed.Running the organizationOrganization settingsThe defaults every workspace inherits: what its container is built with, the board's columns, the git flow, the agent and accounts boxes run on, and the standing instructions every agent reads.
Report a problem