Releases and promote · Parity Docs

A release is one build moving across your environments. Each push to the project's branch makes a build and starts a release, which runs the steps under release: in order.

parity.yaml

environments:
  staging: {}
  production: { services: { web: { replicas: 3 } } }
  acme:   { labels: { fleet: dedicated } }
  globex: { labels: { fleet: dedicated } }

release:
  steps:
    - promote: staging
    - run: e2e
      in: staging
    - block: Ship to production
      prompt: Check the release notes and the on-call calendar.
    - promote: production
    - wait: 1h
      label: Soak
    - promote: { labels: { fleet: dedicated } }
      max_parallel: 1

Inside one environment, a promote runs that environment's rollout: its deploy steps, health checks and traffic switch.

Step types

Step	Fields	Does
`promote: <environment>`	A name, a list, or `{ labels: { … } }`; `max_parallel`	Rolls the build out to each environment and waits for every rollout.
`block: <label>`	`prompt`, `approvals` (1), `allow_author` (true), `timeout` (24h)	Waits for people with `environments.deploy` to approve. A rejection ends the release.
`wait: <duration>`	Or `{ until: <cron>, time_zone }`	A soak, or the next time a schedule names, such as a weekly release train.
`run: <job>`	`in: <environment>`, `retry`, `timeout` (1h)	Runs a job from `jobs:` against that environment, with its settings and secrets. The environment must be promoted by an earlier step.
`group: [steps]`		Runs its steps in parallel, and passes when all of them pass.

Every step also takes label (what people see) and key (what the CLI and API name it by). Keys default to promote-<environment>, run-<job>, wait or the block's label, made lowercase.

Without release:, a project with environments promotes each one in the order declared, with a block before every environment after the first.

Rules

One image per build. The first rollout builds the images. Every later promote of the release runs those images, never a rebuild. Services a push didn't change keep the image the environment already runs, when it runs the build just before; an environment that missed builds rebuilds every service.
Newer builds win. When a newer build reaches the step where an older release waits (a block, a wait, a held promote), the older release is superseded. A promote whose rollouts started finishes. A release never rolls an environment back to an older build.
Freezes hold. A promote into a frozen environment shows as held until the freeze lifts.
Approvals. approvals: 2 needs two different people. allow_author: false doesn't count the approval of the person who pushed the commit; for a GitHub push that means approving from the console, or with a token made there, so Parity knows who you are. A block can't be approved after its timeout.
Skip. Anyone with environments.deploy can skip a wait, run or promote that hasn't finished, with a reason that stays in the release's record. Blocks are approved or rejected, never skipped, and a promote whose rollouts started finishes.
Agents read, people decide. Agents see releases through release_status, and can't approve, reject, skip or promote.

Terminal

parity releases                      # newest first, with what each waits for
parity releases 42                   # one release's steps
parity approve ship-to-production    # the newest release waiting there
parity reject ship-to-production -m "error rate up on staging"
parity skip soak -m "hotfix for the checkout outage" --release 42

Promote by hand

parity promote <environment> ships a release's build into an environment, outside the release's steps: by default the newest release whose build rolled out somewhere and that didn't fail or get rejected; --release <n> picks another. Use it for a hotfix that skips a step or a customer held on a specific build. It is refused while the environment is frozen.

parity promote without an environment makes your local parity.yaml the project's current manifest, the one new builds use. A merge to the default branch does the same.

Rollback

parity rollback <environment> returns the environment to the build it ran before (or --to <commit>, among its last five). It skips deploy jobs and is never blocked by a freeze.

A rollback pins the environment: releases hold their promotes into it until someone promotes it by hand. The previous revision stays warm for 10 minutes after a switch, so a rollback inside that window is a traffic change.

Freezes

A freeze holds deploys to an environment, with a note saying why.

Terminal

parity freeze production -m "Black Friday: no deploys until Monday" --for 72h
parity freeze                  # list freezes
parity unfreeze production

Releases hold their promotes into a frozen environment. A person's promote fails with deploy_frozen, the note, who froze it and when.
--for or --until lifts it automatically. Freezing again replaces the note.
Rollback still works.
Setting and lifting a freeze needs environments.deploy and a project token. A sandbox token can't set or lift one.