Protect a deployment with an environment

Decide which branches may deploy to an environment, who must approve each deployment, and how long it waits.

Last updated 18 November 2026View as Markdown

An environment belongs to a repository and applies to workflows under .github/workflows/. A job that says environment: production (or environment: ${{ inputs.environment }}) deploys to it: the environment's rules decide whether the job may run, and its variables and secrets apply to that job only. A workflow that names an environment the repository does not have creates it, with no rules.

Replace repo-id with the repository's id and production with the environment's name.

Prerequisites

  • ci:PutEnvironment on the repository (rn:ews::<organization id>:ci:repository/<repository id>) to create an environment or change its rules; ci:ListEnvironments to list them; ci:DeleteEnvironment to delete one.
  • The IAM user ids of the reviewers, from your organization.

Set the rules

Field Effect
deploymentBranchPolicy all (the default): any ref. protected: only branches a branch protection rule covers. custom: only refs that match deploymentPatterns
deploymentPatterns Up to 50 { "type": "branch" | "tag", "pattern": "release/*" }; a branch pattern never admits a tag, nor a tag pattern a branch
reviewers Up to six IAM users of your organization; one of them must approve each job
preventSelfReview The person who started the run cannot approve it
waitTimerMinutes Minutes the job waits, counted from when it reaches the environment, 0 to 43,200
url A URL stored with the environment and returned by ci environments list

The console has no page for environments; it shows the jobs waiting at one on the run's page.

dcloud ci environments put repo-id production \
  --deployment-branch-policy protected \
  --reviewers iam-user-id --prevent-self-review

The answer is 200 with the environment, whether it was created or changed. A field you leave out keeps its value; a new environment starts with policy all, no reviewers and no timer.

  • 400 "Invalid environment name" for a name with quotes, backticks, commas, semicolons, backslashes or control characters.
  • 400 "Reviewer … is not a user of this organization".
  • 400 "A custom deployment policy needs at least one branch or tag pattern" when the request sets custom without deploymentPatterns, even if the environment has patterns already.

Result

For a job of the environment in a run planned after the change:

  • On a ref the policy does not admit, the job fails with "Branch "feature-x" is not allowed to deploy to production due to environment protection rules." (or "Tag "…""). On the one-machine-per-run hosted machines it fails at its only step, Environment protection rules.
  • With reviewers or a timer, the job waits while nobody has decided, or while its timer runs. The timer runs from the job's arrival, at the same time as the review. Approve or reject it as in Review a deployment.

Where the job waits depends on where it runs:

  • On the one-machine-per-run hosted machines, the job starts and its first step, Wait for production protection rules, waits and prints who it waits for. The run's two-hour limit still applies and ends a longer wait.
  • On your own runners and runner pools, the job is not handed to any machine until it may go on, so nothing of the environment reaches a machine before then. A job nobody reviews within 5 h 30 min expires.

An unapproved job gets no OIDC token even if it asks for one.

An environment's secrets are those of the secrets environment with the same slug (see Give a job a secret). On the hosted machines, a job of an environment with reviewers that reads such secrets fails at its step Environment protection rules, because every job of a run runs side by side there; deploy with an OIDC token instead (see Deploy with an OIDC token).

Delete an environment

dcloud ci environments delete repo-id production

Its variables and approvals go with it. A workflow that names it again creates it again, without rules.

Did this page help you?