Lesson 6 of 8 in CI/CD pipelines
Environments and approvals
An environment is a named deployment target, such as staging or production, that has its own secrets, variables and protection rules. A job that names an environment waits until every rule passes before it is given to a runner.
Draft. This lesson is written and waiting for a person to run every command and review it. It is safe to learn from, but check the official documentation for anything you depend on.
Read these first: Secrets and variables in pipelines
The problem this solves
A pipeline that deploys on every push to production has no pause where a person can say not yet. It also gives every job in the workflow the production credentials, including jobs that only run tests.
Environments add a gate and a scope. The gate is a rule such as required reviewers. The scope means that secrets stored on the environment are released only to a job that targets it, and only after the rules pass.
How it works
- Runs code
- Control
- People and clients
- Security
The deploy job reaches its environment, the protection rules ask a reviewer, and once approved the job starts with the environment's secrets and deploys.
- Deploy job to Protection rules: 1 job reaches deploy
- Protection rules to Reviewer: 2 asks for review
- Reviewer to Job starts: 3 approve
- Job starts to Target: 4 deploy
You add environment: production to a job. GitHub shows the job as waiting, evaluates the environment's rules, and only then sends the job to a runner. Rejecting the review fails the workflow.
Rules you can set include required reviewers, a wait timer, and limits on which branches may deploy. You can also block the person who started the run from approving it. Which of these are available depends on your plan and whether the repository is public or private, so check the current GitHub documentation for your account.
Environment secrets are only released after approval. That means a test job cannot read production credentials even if someone edits it, because the test job does not name the environment.
GitLab uses protected environments and manual jobs for the same purpose, and Jenkins has an input step. The idea of a gate before production is shared.
Try it yourself
Use the ci-demo repository. The deploy job only echoes a message, so nothing is actually deployed.
- 1Add a deploy job tied to an environment
cat > .github/workflows/env-demo.yml <<'EOF' name: env-demo on: workflow_dispatch: permissions: contents: read jobs: test: runs-on: ubuntu-latest timeout-minutes: 5 steps: - run: echo "tests would run here" deploy: needs: test runs-on: ubuntu-latest timeout-minutes: 5 environment: staging steps: - run: echo "deploying $GITHUB_SHA to staging" EOF git add . git commit -m "Add environment demo" git push gh workflow run env-demo.ymlReferencing an environment name that does not exist yet creates it. If you do not use
gh, press Run workflow on the Actions tab instead. - 2Add a required reviewer and run again
In the repository, open Settings, then Environments, then
staging. Turn on Required reviewers and add yourself. Run the workflow again. The deploy job should stop in a waiting state and a Review deployments button appears on the run. If the option is missing for your account type, you can still read the rest of this concept and skip this step. - 3Approve and watch it continue
Click Review deployments, tick
staging, and approve. The job now starts. If the environment blocks self-review, ask a second person to approve or turn that setting off for this throwaway repository.
What breaks, and where to look
The deploy job sits in a waiting state and nobody notices for hours.
- WHY IT HAPPENS
- A required reviewer has not been told or is on leave, or the reviewer list is empty or wrong so the right person never sees the request.
- CHECK FIRST
- Open the run page, look for the Review deployments button, and check Settings, Environments for who the reviewers are.
A deploy step fails because a secret that exists in the settings is empty.
- WHY IT HAPPENS
- The secret is stored on the environment, but the job has no
environment:line, so it never receives it. - CHECK FIRST
- Confirm the job that reads the secret has
environment: <name>with the exact same name as in Settings, Environments.
When not to use this
- An approval gate on every deploy of a small personal site only slows you down. Use gates where a mistake is costly.
- An approval is only as good as the reviewer. If people click approve without looking, the gate gives false comfort.
Check yourself
What does the environment: key on a job do?
It ties the job to a named environment, so protection rules must pass first and that environment's secrets are available to it.
Why are production secrets safer on an environment than on the repository?
Only jobs that name the environment, after its rules pass, receive them, so test jobs never see them.
What happens to the workflow if a reviewer rejects the deployment?
The waiting job does not run and the workflow fails.
Keep going
Lesson 52 of 92 in the DevOps path