7 min read

Automate S3 Deployments with GitHub Actions and OIDC

Pipeline diagram: a git push to GitHub triggers GitHub Actions, which assumes an AWS IAM role through OIDC and syncs files to an S3 bucket.

Uploading a static website to S3 by hand is fine for a one-off, but it gets tedious once you update the site often. This guide shows how to deploy a static website to Amazon S3 from GitHub Actions on every push to main, using OpenID Connect (OIDC) instead of stored AWS access keys. GitHub proves its identity to AWS and receives short-lived credentials, so there is no long-lived secret to leak or rotate.

What you’ll build: a pipeline that publishes your site whenever main changes. My latest run took 20 seconds from push to finished deployment.

GitHub Actions run showing the Sync to S3 job completed successfully in 20 seconds

I built this for my Cloud Docs Hub project, and the setup below is what it uses.

What you need

  • An AWS account where you can create S3 buckets and IAM roles
  • A GitHub repository that contains your static site (HTML, CSS and JavaScript)
  • About 20 minutes

Step 1: Prepare the S3 bucket

Set the bucket up for static website hosting first:

  1. Create the bucket. Bucket names are global, so pick one nobody else has used, such as cloud-docs-hub.
  2. Allow public reads. Under Permissions, turn off Block all public access and confirm. This is required because visitors load the site straight from S3.
  3. Enable static website hosting. Under Properties, switch on Static website hosting and set index.html as the index document.
  4. Add a bucket policy that lets anyone read objects:
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "PublicReadGetObject",
      "Effect": "Allow",
      "Principal": "*",
      "Action": "s3:GetObject",
      "Resource": "arn:aws:s3:::cloud-docs-hub/*"
    }
  ]
}

Step 2: Set up keyless authentication with OIDC

Instead of creating an IAM user with access keys, you create an IAM role that trusts GitHub’s OIDC provider.

Add GitHub as an identity provider

If your account doesn’t have it yet:

  1. Open the IAM console, go to Identity providers, and choose Add provider.
  2. Select OpenID Connect.
  3. Set the provider URL to https://token.actions.githubusercontent.com.
  4. Set the audience to sts.amazonaws.com.

Create the IAM role and trust policy

Create a role that uses a web identity trust policy. There is one catch to know about first.

GitHub is changing the default sub claim in its OIDC tokens to include permanent numeric IDs. For repositories created after July 15, 2026, or ones that opt in, the claim looks like repo:OWNER@OWNER-ID/REPO@REPO-ID:ref:refs/heads/main. A trust policy that matches the old name-only format with an exact string will fail with Not authorized to perform sts:AssumeRoleWithWebIdentity. GitHub describes the change in its changelog.

A StringLike condition with wildcards matches both formats:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
        },
        "StringLike": {
          "token.actions.githubusercontent.com:sub": "repo:<OWNER>*/cloud-docs-hub*:*"
        }
      }
    }
  ]
}

IAM role trust policy in the AWS console, with account details blurred

Tighten the trust policy

The wildcards above are convenient but broad. <OWNER>* also matches any other account whose name starts with yours, cloud-docs-hub* matches any repository whose name starts with it, and the trailing :* accepts every branch and pull request.

For a stricter policy, pin the numeric IDs and the branch. AWS exposes the repository and owner IDs as condition keys:

"Condition": {
  "StringEquals": {
    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
    "token.actions.githubusercontent.com:repository_owner_id": "<OWNER_ID>",
    "token.actions.githubusercontent.com:repository_id": "<REPO_ID>"
  },
  "StringLike": {
    "token.actions.githubusercontent.com:sub": "repo:<OWNER>@*/cloud-docs-hub@*:ref:refs/heads/main"
  }
}

Find the IDs with the GitHub CLI:

gh api users/<OWNER> --jq .id
gh api repos/<OWNER>/cloud-docs-hub --jq .id

Run the workflow again after any change to the policy to confirm it still works.

Step 3: Give the role least-privilege S3 access

The workflow uses aws s3 sync, which needs permissions at two levels:

  • Bucket level (arn:aws:s3:::cloud-docs-hub): s3:ListBucket, so the command can compare the bucket with your repository.
  • Object level (arn:aws:s3:::cloud-docs-hub/*): s3:PutObject, s3:GetObject and s3:DeleteObject, so it can upload new files and remove old ones.

Attach this inline policy to the role:

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "S3DeploymentPermissions",
      "Effect": "Allow",
      "Action": [
        "s3:PutObject",
        "s3:GetObject",
        "s3:DeleteObject",
        "s3:ListBucket"
      ],
      "Resource": [
        "arn:aws:s3:::cloud-docs-hub",
        "arn:aws:s3:::cloud-docs-hub/*"
      ]
    }
  ]
}

IAM policy summary showing limited list, read and write access to S3

Step 4: Write the GitHub Actions workflow

Create .github/workflows/deploy.yml in your repository:

name: Deploy CloudDocs Hub to AWS S3

on:
  push:
    branches: [main]
  workflow_dispatch:

permissions:
  id-token: write   # lets the job request an OIDC token
  contents: read    # lets the job check out the code

jobs:
  deploy:
    name: Sync to S3
    runs-on: ubuntu-latest
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4

      - name: Configure AWS credentials via OIDC
        uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: us-east-1

      - name: Deploy to S3
        run: |
          aws s3 sync . s3://${{ secrets.AWS_S3_BUCKET }}/ \
            --delete \
            --cache-control "no-cache" \
            --exclude ".git/*" \
            --exclude ".github/*" \
            --exclude "README.md"

How the pieces work:

  1. id-token: write allows the job to request an OIDC token from GitHub. Without it, the AWS step has nothing to exchange.
  2. configure-aws-credentials trades that token for temporary AWS credentials by assuming the role named in the AWS_ROLE_ARN secret.
  3. aws s3 sync --delete uploads changed files and removes objects that no longer exist in the repository, so the bucket always mirrors main. Because of --delete, anything else you keep in this bucket will be removed, so use a dedicated bucket.
  4. The excludes keep repository files such as .git and the README out of the bucket.

Step 5: Add secrets and test the pipeline

  1. In GitHub, go to Settings, then Secrets and variables, then Actions.
  2. Add two repository secrets:
    • AWS_ROLE_ARN: the ARN of the role, such as arn:aws:iam::<ACCOUNT_ID>:role/GitHubActions
    • AWS_S3_BUCKET: the bucket name, such as cloud-docs-hub
  3. Commit the workflow and push to main.

Open the Actions tab to watch the run. When it finishes, your HTML, CSS and JavaScript files are in the bucket.

S3 bucket listing showing index.html and the assets folder after the first deployment

Common errors and how to fix them

Error Cause Fix
Not authorized to perform sts:AssumeRoleWithWebIdentity The trust policy’s sub condition doesn’t match GitHub’s token, often because of the new immutable format Use the wildcard or ID-based conditions from Step 2
AccessDenied during aws s3 sync The IAM policy only lists the object ARN, so the command can’t list the bucket Include both the bucket ARN and the /* object ARN
The AWS step can’t get a token id-token: write is missing from the workflow Add it under permissions

Key takeaways

  • Add id-token: write to the workflow so GitHub can issue an OIDC token.
  • Write the trust policy to handle GitHub’s immutable sub claims, and tighten it with numeric IDs and a branch once it works.
  • Include both the bucket ARN and the object ARN in the IAM policy so aws s3 sync can list and write.
  • Use a dedicated bucket, because --delete removes anything the repository doesn’t contain.

Next steps

The S3 website endpoint only serves plain HTTP, and Chrome now warns before loading public HTTP sites. The natural upgrade is to put CloudFront with a free ACM certificate in front of the bucket, and make the bucket private with origin access control.