Lesson 6 of 7 in Security basics for DevOps

Securing your CI/CD pipeline

Core12 min

A CI/CD pipeline can build, test and deploy your software, so whoever controls it controls production. Securing it means giving jobs the smallest token they need, letting them obtain short-lived cloud credentials instead of stored keys, and treating every third-party step as code you are running.

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: Keeping secrets out of git and images, Least privilege for people, jobs and containers, CI/CD pipelines

The problem this solves

A pipeline sits in a powerful place. It holds credentials to deploy, it runs code from your repo and from third-party actions, and it is triggered automatically. A long-lived cloud key stored as a repository secret is a standing prize: if it leaks, it works from anywhere until someone revokes it.

Third-party actions add a second risk. A step such as uses: some-org/some-action@v1 runs that project's code with your job's access. A tag like v1 can be moved by the maintainer, or by someone who takes over their account, so tomorrow's run may execute different code than the code you reviewed.

How it works

A job proves who it is and gets credentials that expire
A job proves who it is and gets credentials that expireThe job asks GitHub for a signed identity token, presents it to the cloud, the cloud checks the token against its trust rule, and returns temporary credentials.1 ask fortoken2 presenttoken3 claims match, issue4 short-lived accessGitHub OIDCissues a job tokenCI jobneeds cloud accessCloud trust rulechecks repo and branchTemporary accessexpires after the job
  • Security
  • Runs code

The job asks GitHub for a signed identity token, presents it to the cloud, the cloud checks the token against its trust rule, and returns temporary credentials.

  1. CI job to GitHub OIDC: 1 ask for token
  2. CI job to Cloud trust rule: 2 present token
  3. Cloud trust rule to Temporary access: 3 claims match, issue
  4. Temporary access to CI job: 4 short-lived access

OpenID Connect (OIDC) lets the pipeline show an identity instead of a password. When a job runs, GitHub can issue it a signed token whose claims say which repository and which branch or environment it is running for. You configure the cloud provider once to trust tokens that match specific claims, and the cloud then hands the job credentials that expire.

Nothing long-lived is stored in the repository. A leaked log or a copied secret cannot be reused later, because the credentials die with the job. The trust rule is the security boundary, so make it specific: name the exact repository and the branch or environment, not a pattern that matches everything.

Two more habits cover the rest. First, set the pipeline's own token to read-only by default and grant extra permission per job, such as id-token: write only on the job that needs the cloud. Second, pin third-party actions to a full 40-character commit SHA, which cannot be moved the way a tag can, and let an update tool propose new ones for review.

Try it yourself

You do not need a cloud account for these steps. You will write a sample workflow file into a throwaway folder and audit it with grep. Nothing is run on GitHub.

  1. 1
    Write a sample workflow
    mkdir -p ~/pipeline-demo/.github/workflows && cd ~/pipeline-demo
    cat > .github/workflows/deploy.yml <<'EOF'
    name: deploy-demo
    on: push
    permissions:
      contents: read
    jobs:
      deploy:
        runs-on: ubuntu-latest
        permissions:
          contents: read
          id-token: write
        steps:
          - uses: actions/checkout@v4
          - uses: aws-actions/configure-aws-credentials@v4
            with:
              role-to-assume: arn:aws:iam::<account-id>:role/<deploy-role>
              aws-region: <region>
    EOF

    The top level permissions block makes the default token read-only. The job adds id-token: write so it may request an OIDC token. There is no access key anywhere in the file.

  2. 2
    Find actions that are not pinned to a commit SHA
    grep -rn 'uses:' .github/workflows | grep -vE '@[0-9a-f]{40}' | grep -v 'uses: \./'

    The first grep lists every uses: line. The second removes the ones already pinned to a 40-character hexadecimal SHA, and the third ignores local actions. Both lines in the sample are reported because they use tags.

  3. 3
    Look up the commit behind a tag
    git ls-remote https://github.com/actions/checkout 'refs/tags/v4*'

    This reads public data and changes nothing. If a tag is annotated you may see two lines, and the commit SHA is the one whose name ends in ^{}. Check that the SHA belongs to the action's own repository, then write it in the workflow as uses: actions/checkout@<full-sha> # v4 so people can still read the version.

  4. 4
    Know what the cloud side would check
    echo 'repo:<owner>/<repo>:ref:refs/heads/main'

    This is the shape of the sub claim for a run on the main branch. In the cloud trust rule you would require a value like this exactly, so a pull request from a fork or another branch cannot get credentials. Clean up with rm -r ~/pipeline-demo.

What breaks, and where to look

  • Unable to get ACTIONS_ID_TOKEN_REQUEST_URL env variable

    WHY IT HAPPENS
    The job asked for an OIDC token but is not allowed to request one. The id-token: write permission is missing on that job.
    CHECK FIRST
    Open the workflow and add permissions: id-token: write to the job that authenticates. Check that a workflow-level permissions block did not remove it.
  • Not authorized to perform sts:AssumeRoleWithWebIdentity when assuming a role.

    WHY IT HAPPENS
    The token was valid, but its claims do not match the cloud trust rule. A common reason is a rule that expects the main branch while the job ran on another branch or for an environment.
    CHECK FIRST
    Compare the repository and branch of the failing run with the condition on the role's trust policy, especially the sub value.
  • Resource not accessible by integration when a step tries to comment on a PR or push a tag.

    WHY IT HAPPENS
    The default token is read-only, which is the safer setting, and the step needs a write permission you have not granted.
    CHECK FIRST
    Find which API the step calls, then add only that permission, such as pull-requests: write, to that one job.

When not to use this

  • Self-hosted runners and other CI systems have their own mechanisms. The ideas carry over (short-lived identity, narrow tokens, reviewed third-party code), but the settings are different, so check your platform's documentation.
  • Pinning to a SHA stops silent changes and does not make an action trustworthy. You still need to read what it does or choose maintained actions from sources you trust.

Check yourself

Why is OIDC better than a stored cloud access key?

The job receives credentials that expire after the run, so there is no standing key to leak or reuse later.

Why pin a third-party action to a commit SHA?

Tags can be moved to different code, and a commit SHA always refers to the same code you reviewed.

Which permission lets a job request an OIDC token?

id-token: write on that job. Give it only to the jobs that need cloud access.

Lesson 91 of 92 in the DevOps path

Search

Search cheat sheets and projects