Skip to content
Source
Sign inSign up

Deploy to AWS

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 sub claim names the repository and the ref. With this policy, only runs of main in acme/app get the role.
  • AWS matches only aud and sub. It cannot read the trust claim.

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 deploy is your own deploy script. The AWS CLI and each AWS SDK read AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE, and trade the token with STS for keys.
  • egress lists 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.