GitHub OIDC and Terraform: short-lived model credentials in CI
Federate GitHub Actions OIDC to a cloud IAM role so each run gets temporary credentials and the repository stores no model key. Condition the trust policy on the exact repository and branch (or environment) in the sub claim, scope the role to the models the job calls, and never let code from a fork run with it.
If a CI job calls a model, it needs model credentials, and a long-lived API key in repository secrets is the wrong place to keep them. Federate GitHub Actions OIDC to a cloud IAM role instead: each run proves which repository and branch it comes from with a signed token, receives temporary credentials, and the repository stores nothing worth stealing. I built this for the LLM-backed scanner in the CI gates for agent skills I own at Okta (Auth0): a Terraform module and GitHub OIDC-federated IAM roles that supply short-lived model credentials with no long-lived secrets. The example below is a generic version written for this post, not that module, and uses AWS, with Amazon Bedrock standing in for any model endpoint that accepts cloud IAM credentials.
Why a long-lived model key in CI is a liability
A stored key works for anyone who has a copy, from anywhere, until someone rotates it. CI offers many ways to get a copy: a log line, a compromised third-party action, a malicious dependency in the build, or a workflow that runs untrusted code with secrets in scope. A leaked model key is also spendable, so whoever holds it can run up your bill.
Federation removes the stored key. There is nothing to rotate, the credentials expire on their own, and the trust policy states exactly which workflow may use the role.
How GitHub Actions OIDC federation with AWS works
- The job declares
permissions: id-token: write, which lets it request an OIDC token from GitHub. On its own, this grants nothing in AWS. - GitHub issues a signed JWT from
https://token.actions.githubusercontent.com. Its claims describe the run, including the audience (aud) and a subject (sub) such asrepo:example-org/example-repo:ref:refs/heads/main. - The aws-actions/configure-aws-credentials action sends the token to AWS STS with
AssumeRoleWithWebIdentity. - STS checks the role's trust policy: the token must come from the OIDC provider registered in your account, with the audience
sts.amazonaws.comand asubthat the policy accepts. - STS returns temporary credentials for the role, and the action exports them to the steps that follow.
GitHub's page on security hardening with OpenID Connect documents the sub format and the other claims. Read it before you write a condition, because the subject changes with the trigger: a branch push, a pull request and a job that uses an environment each produce a different one.
The Terraform: a role only one branch can assume
The OIDC provider for token.actions.githubusercontent.com is created once per AWS account, so this example looks it up instead of creating it. The role trusts exactly one repository and branch, and it may call only the models you list.
variable "github_repo" {
description = "ORG/REPO allowed to assume the role"
type = string
}
variable "model_arns" {
description = "Exact model or inference profile ARNs the job may invoke"
type = list(string)
}
data "aws_iam_openid_connect_provider" "github" {
url = "https://token.actions.githubusercontent.com"
}
data "aws_iam_policy_document" "trust" {
statement {
actions = ["sts:AssumeRoleWithWebIdentity"]
principals {
type = "Federated"
identifiers = [data.aws_iam_openid_connect_provider.github.arn]
}
condition {
test = "StringEquals"
variable = "token.actions.githubusercontent.com:aud"
values = ["sts.amazonaws.com"]
}
condition {
test = "StringEquals"
variable = "token.actions.githubusercontent.com:sub"
values = ["repo:${var.github_repo}:ref:refs/heads/main"]
}
}
}
resource "aws_iam_role" "model_ci" {
name = "ci-model-access"
assume_role_policy = data.aws_iam_policy_document.trust.json
max_session_duration = 3600
}
data "aws_iam_policy_document" "invoke" {
statement {
actions = ["bedrock:InvokeModel"]
resources = var.model_arns
}
}
resource "aws_iam_role_policy" "invoke" {
name = "invoke-models"
role = aws_iam_role.model_ci.id
policy = data.aws_iam_policy_document.invoke.json
}
output "role_arn" {
value = aws_iam_role.model_ci.arn
}
Three choices in it are deliberate:
StringEqualsonsub, notStringLike. An exact match cannot be widened by a wildcard you did not think through.- The
audcondition. It ties the token to STS, which is the audience the action requests by default. bedrock:InvokeModelon named ARNs. The role can call the listed models and nothing else. If the job uses the streaming APIs, addbedrock:InvokeModelWithResponseStream.
The workflow
name: model-scan
on:
push:
branches: [main]
permissions:
contents: read
id-token: write
jobs:
scan:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: aws-actions/configure-aws-credentials@v4
with:
role-to-assume: ${{ vars.MODEL_ROLE_ARN }}
aws-region: us-east-1
role-duration-seconds: 900
- run: ./scripts/scan.sh
A few notes on it:
- Once you set
permissions, every permission you leave out is set to none, which is what you want.contents: readis there so that checkout still works. - The role ARN is not a secret. A repository variable keeps it out of the workflow file without pretending it is sensitive.
- 900 seconds is the shortest session STS allows for this call. Pick the shortest duration that covers the job.
- In production, pin third-party actions to a full commit SHA rather than a version tag, as GitHub's security hardening guidance recommends.
Pitfalls a working setup hides
Every mistake below still produces a green build. That is what makes them dangerous: a trust policy that is too broad works perfectly.
A sub condition that is too broad, or missing
- No
subcondition. Any GitHub workflow can request a token with the audiencests.amazonaws.com, so a policy that checks onlyaudtrusts every repository on GitHub that knows your role ARN. repo:example-org/*. This trusts every repository in the organization, including new ones that anyone allowed to create repositories can add.repo:example-org/example-repo:*. This trusts every branch, tag, environment and pull request in the repository. Anyone who can push a branch can run a workflow that assumes the role, and branch protection onmaindoes not help.
Keep the condition exact, and if several refs need access, list each one. For deployment-style jobs, require a GitHub environment with protection rules and match repo:ORG/REPO:environment:NAME, so a reviewer or a branch rule stands between a commit and the credentials.
Pull requests from forks
A pull_request workflow triggered from a fork runs without your secrets and with a read-only GITHUB_TOKEN. That default is correct. The danger is the workaround: pull_request_target runs in the context of the base repository, with its permissions. If such a workflow grants id-token: write and then checks out and runs the pull request's code, a stranger's code can request credentials for your role. Do not count on the sub condition to catch this; check what your trigger produces, and keep untrusted code out of any job that can reach the role.
If you want a model to review outside contributions, run it in a job that never executes the contribution, treat the contribution as untrusted data, and give that job the narrowest role you have. Running the credentialed step after merge is simpler still.
A role that can do more than the job needs
bedrock:*, or a resource of *, turns a scanner's credentials into general cloud access. One role per purpose keeps a token minted for scanning from doing anything else.
Testing only the success path
Prove that the policy refuses what it should. Run the same workflow from a feature branch (a workflow_dispatch trigger makes this easy) and confirm that the credentials step fails with an access denied error from STS. A trust policy you have only seen succeed is untested.
Trade-offs
- More moving parts. An OIDC provider, a role, a trust policy and a variable replace one secret, and the "Not authorized to perform sts:AssumeRoleWithWebIdentity" error tells you little about which condition failed.
- Exact conditions break on renames. Rename the repository or the branch and the job loses access. That is failing closed, which I prefer, but put it on the rename checklist.
- Temporary credentials can still leak. A compromised step can use them while they are valid. Short sessions and narrow permissions limit the damage; they do not remove it.
- Not every model provider federates. If yours only issues API keys, keep the key in a cloud secret manager that only the federated role can read. The key never sits in GitHub, but it is still long-lived, so treat this as a fallback, not the goal. Google Cloud Workload Identity Federation and Azure federated credentials also accept GitHub's OIDC tokens, so the pattern works beyond AWS.
If you are wiring models into CI, or giving agents identities of their own, and want the trust boundaries reviewed, I take on consulting and advisory work: work with me.
FAQ
How does GitHub Actions OIDC work with AWS?
A job with the id-token: write permission asks GitHub for a signed OpenID Connect token that describes the run, including the repository, the ref and the trigger. The aws-actions/configure-aws-credentials action sends that token to AWS STS with AssumeRoleWithWebIdentity. If the role's trust policy accepts the token's issuer, audience and sub claim, STS returns temporary credentials for the role, and no AWS key is ever stored in GitHub.
What should the sub condition be in a GitHub OIDC trust policy?
As narrow as the job allows. For a workflow that runs on one branch, use StringEquals with repo:ORG/REPO:ref:refs/heads/main. For deployment-style jobs, require a GitHub environment with protection rules and match repo:ORG/REPO:environment:NAME. Avoid wildcards such as repo:ORG/* or repo:ORG/REPO:*, which trust every repository or every branch and pull request, and never leave the sub condition out.
Can pull requests from forks use GitHub OIDC credentials?
They should not. A pull_request workflow triggered from a fork runs without your secrets and with a read-only token, which is the right default. The risk is pull_request_target, which runs in the context of the base repository. If such a workflow grants id-token: write and then checks out and runs the fork's code, untrusted code can request credentials for your role.