Deployments

Know what runs where, and who let it

Workflow jobs record their deployments, and other tools can record theirs. A protected environment takes only protected tags and waits for a person, and an earlier deployment can run again.

RegisterRead the docs

Environments

Every deployment on record

A job with environment: production records a deployment, and its status follows the job. Deployments by other tools are recorded with bscope deploy record or the API, by people with write access or apps granted deployments:write. Branchscope records deployments; it doesn't run them.

~/invoices
$ bscope deploy record production --ref v1.4.0 --url https://invoices.example.com
Recorded deployment 12: succeeded of v1.4.0 (3fb94140) to production.
$ bscope deploy record staging --ref main --status in_progress -m "Rolling out"
Recorded deployment 13: in_progress of main (7e4f0b12) to staging.
$ bscope deploy status 13 succeeded
Set deployment 13: succeeded of main (7e4f0b12) to staging.

Required reviewers

Deployments that wait for a person

A protected environment can make its job wait until one of up to 10 reviewers approves it, and then for a wait timer. With Prevent self-review, on by default, whoever set off the run can't approve it, and agents can't approve at all. Until then the job doesn't start and gets no secrets.

acme/invoices › Deployments
  • production v1.4.0Only from protected tags matching v*waiting
  • staging v1.4.0succeeded

deploy deploys to production and is waiting for review by bob, carol. It won't start, or get the environment's secrets, until one of them approves it.

Approve and deployReject

Protected tags

Production only from a release tag

Give an environment a tag pattern such as v*, and deployments to it must come from a matching tag that a tag ruleset stops being moved. A job from a branch is refused before its first step, and its run says why. Only a person changes an environment's protection, never an agent.

acme/invoices › Runs › Ship #8
  • staging mainpassed
  • production mainOnly from protected tags matching v*failed

Refused: production only takes deployments from a tag matching v* that a tag ruleset protects; this one is from the branch main

Secrets

Secrets, kept from agents' runs

Repository, organization and environment secrets are encrypted, can't be read back, and are masked in logs. A job gets only the ones it names, an environment's only when it deploys there and its protection has passed, and a run an agent set off gets none until an administrator approves it. For AWS, Google Cloud and Azure, a short-lived identity token replaces a stored key.

acme/invoices › .branchscope/workflows/release.yml
jobs:
  deploy:
    runs-on: deploy
    environment: production
    secrets: [DEPLOY_KEY]
    permissions:
      id-token: write
    steps:
      - run: ./deploy.sh "$BRANCHSCOPE_TAG"

Deploy again

Roll back, and require what must be deployed

Deploy again runs a deployment's workflow once more, on its tag at its commit: on an earlier deployment, that's a rollback, under the environment's protection like any run. A ruleset can require deployments to succeed, before a change merges into a branch or before a release makes its tag.

acme/invoices › Deployments › 11

production: v1.3.0

From Release, job deploy.

Runs Release again by hand on v1.3.0 at 5a7c0e21. The environment's protection applies.

Deploy again

Put a person between a push and production

Add an environment under Settings → Environments, give it reviewers and a tag pattern, and deploy from a workflow job.

Register