Lesson 6 of 7 in Security basics for DevOps
Securing your CI/CD pipeline
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
- 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.
- CI job to GitHub OIDC: 1 ask for token
- CI job to Cloud trust rule: 2 present token
- Cloud trust rule to Temporary access: 3 claims match, issue
- 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.
- 1Write 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> EOFThe top level
permissionsblock makes the default token read-only. The job addsid-token: writeso it may request an OIDC token. There is no access key anywhere in the file. - 2Find 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
greplists everyuses: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. - 3Look 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 asuses: actions/checkout@<full-sha> # v4so people can still read the version. - 4Know what the cloud side would check
echo 'repo:<owner>/<repo>:ref:refs/heads/main'
This is the shape of the
subclaim 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 withrm -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: writepermission is missing on that job. - CHECK FIRST
- Open the workflow and add
permissions: id-token: writeto the job that authenticates. Check that a workflow-levelpermissionsblock did not remove it.
Not authorized to perform sts:AssumeRoleWithWebIdentitywhen 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
subvalue.
Resource not accessible by integrationwhen 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.
Keep going
Lesson 91 of 92 in the DevOps path