Lesson 6 of 8 in CI/CD pipelines

Environments and approvals

Advanced7 min

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

A deploy job waits for a reviewer
A deploy job waits for a reviewerThe deploy job reaches its environment, the protection rules ask a reviewer, and once approved the job starts with the environment's secrets and deploys.1 jobreachesdeploy2 asks for review3 approve4 deployDeploy jobenvironment: productionProtection rulesrequired reviewersReviewera personJob startssecrets releasedTargetthe real system
  • 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.

  1. Deploy job to Protection rules: 1 job reaches deploy
  2. Protection rules to Reviewer: 2 asks for review
  3. Reviewer to Job starts: 3 approve
  4. 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.

  1. 1
    Add 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.yml

    Referencing an environment name that does not exist yet creates it. If you do not use gh, press Run workflow on the Actions tab instead.

  2. 2
    Add 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.

  3. 3
    Approve 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.

Lesson 52 of 92 in the DevOps path

Search

Search cheat sheets and projects