CI / Secrets and trust
Deploy to AWS with OIDC
Your deploy job needs AWS keys, and an access key that you save as a CI secret works until you revoke it. With OIDC, the job trades a 5-minute token from the forge with AWS for short-lived keys, and the forge holds no AWS key.
2 min read
You need:
- Write access to the repository on TanStack Source, and a workflow. Your first workflow shows how to write one.
- Admin access to your AWS account.
1. Add the forge as an identity provider
In AWS IAM, add an OpenID Connect identity provider:
- Provider URL:
https://source.tanstack.com/oidc - Audience:
sts.amazonaws.com
Or run this with the AWS CLI:
aws iam create-open-id-connect-provider --url https://source.tanstack.com/oidc --client-id-list sts.amazonaws.com
Note
The provider URL is the address of the site, then /oidc. On another deployment of TanStack Source, use its address.
2. Make a role that trusts your branch
Create an IAM role with this trust policy. Replace 123456789012 with your AWS account id, and acme/app with your repository.
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": { "Federated": "arn:aws:iam::123456789012:oidc-provider/source.tanstack.com/oidc" },
"Action": "sts:AssumeRoleWithWebIdentity",
"Condition": {
"StringEquals": {
"source.tanstack.com/oidc:aud": "sts.amazonaws.com",
"source.tanstack.com/oidc:sub": "repo:acme/app:ref:refs/heads/main"
}
}
}
]
}
- The
subclaim names the repository and the ref. With this policy, only runs ofmaininacme/appget the role. - AWS matches only
audandsub. It cannot read thetrustclaim.
Then attach the AWS permissions that your deploy needs to the role.
Important
Give main a branch rule that requires a pull request: src ci rule set main --require-pull. Without it, a person with write access can push code to main alone, and that code gets the role.
3. Ask for the token in the job
Add permissions: { idToken: true } to the deploy job. In a function step, ctx.idToken() returns the token:
import { writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { defineWorkflow, push, setup } from '@tanstack-source/ci'
const ROLE = 'arn:aws:iam::123456789012:role/deploy-app'
export default defineWorkflow('deploy', { on: [push({ branches: ['main'] })] }).job('deploy', {
permissions: { idToken: true },
env: { AWS_REGION: 'us-east-1' },
egress: ['registry.npmjs.org', 'sts.us-east-1.amazonaws.com', 's3.us-east-1.amazonaws.com'],
steps: [
setup.pnpm(),
{ name: 'Install', run: 'pnpm install --frozen-lockfile' },
{
name: 'Deploy',
do: async (ctx) => {
const token = await ctx.idToken({ audience: 'sts.amazonaws.com' })
const file = join(tmpdir(), 'aws-web-identity-token')
await writeFile(file, token, { mode: 0o600 })
await ctx.sh`AWS_ROLE_ARN=${ROLE} AWS_WEB_IDENTITY_TOKEN_FILE=${file} pnpm run deploy`
},
},
],
})
pnpm run deployis your own deploy script. The AWS CLI and each AWS SDK readAWS_ROLE_ARNandAWS_WEB_IDENTITY_TOKEN_FILE, and trade the token with STS for keys.egresslists the STS host of your region and the hosts of the AWS services that you deploy to.- The token file is in the temporary folder of the container, outside the workspace, so no artifact takes it.
A command step can get the token with curl and TANSTACK_SOURCE_OIDC_REQUEST_URL:
{ name: 'Token', run: 'curl -fsS "$TANSTACK_SOURCE_OIDC_REQUEST_URL?audience=sts.amazonaws.com" | jq -r .token > /tmp/aws-web-identity-token' },
{ name: 'Deploy', run: 'pnpm run deploy', env: { AWS_ROLE_ARN: ROLE, AWS_WEB_IDENTITY_TOKEN_FILE: '/tmp/aws-web-identity-token' } },
4. Push to main
git add .source/workflows/deploy.ts
git commit -m "ci: deploy to AWS with OIDC"
git push origin main
Done
Open the run on the CI tab. The Deploy step passes, with the output of your deploy script in its log. The job deployed to AWS, and the forge holds no AWS key.
If the step fails, read When ctx.idToken() fails.