Protect a deployment with an environment
Decide which branches may deploy to an environment, who must approve each deployment, and how long it waits.
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:PutEnvironmenton the repository (rn:ews::<organization id>:ci:repository/<repository id>) to create an environment or change its rules;ci:ListEnvironmentsto list them;ci:DeleteEnvironmentto 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-reviewPUT /ci/api/repositories/repo-id/environments/production
{
"deploymentBranchPolicy": "custom",
"deploymentPatterns": [{ "type": "branch", "pattern": "release/*" }],
"reviewers": ["3f0c9a52-5d0e-4c1a-9d39-0b8a3e0f6a11"],
"preventSelfReview": true
}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 setscustomwithoutdeploymentPatterns, 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 productionIts variables and approvals go with it. A workflow that names it again creates it again, without rules.