Deploy Static Web Apps to AWS S3 Using GitHub Actions

This guide will help you securely deploy a static web application (e.g., Next.js, Vite) to an AWS S3 bucket using GitHub Actions and an IAM Role.

Step 1: Create an IAM Role in AWS

1. Log in to the AWS Management Console and navigate to IAM > Roles.

2. Click Create Role.

3. Select Web Identity as the trusted entity type.

4. Under Identity Provider, choose token.actions.githubusercontent.com. If it doesn’t exist:

   • Click Create Provider.

   • Set Provider Type to OpenID Connect.

   • Enter token.actions.githubusercontent.com as the Provider URL.

   • Set sts.amazonaws.com as the Audience.

   • Click Save.

5. Return to the Create Role screen, select token.actions.githubusercontent.com, and confirm sts.amazonaws.com as the audience.

6. Add Permissions: Choose a policy like AdministratorAccess (for simplicity) or a custom policy with least privilege for production.

7. Set Trust Policy: Ensure the policy matches the following (replace placeholders with your values):

{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": {
        "Federated": "arn:aws:iam::<AWS_ACCOUNT_ID>:oidc-provider/token.actions.githubusercontent.com"
      },
      "Action": "sts:AssumeRoleWithWebIdentity",
      "Condition": {
        "StringEquals": {
          "token.actions.githubusercontent.com:aud": "sts.amazonaws.com",
          "token.actions.githubusercontent.com:sub": "repo:<GITHUB_USERNAME>/<REPO_NAME>:ref:refs/heads/<BRANCH_NAME>"
        }
      }
    }
  ]
}

1. Name the Role (e.g., GitHubActionsRole) and click Create Role.

Step 2: Configure GitHub Repository Secrets

1. Go to your GitHub repository.

2. Navigate to Settings > Secrets and Variables > Actions.

3. Add the following secrets:

   • AWS_ROLE_ARN: The ARN of the IAM role (e.g., arn:aws:iam::<AWS_ACCOUNT_ID>:role/GitHubActionsRole).

   • AWS_REGION: Your AWS region (e.g., us-east-1).

   • S3_BUCKET: The name of your S3 bucket (e.g., my-app-bucket).

Step 3: Create a GitHub Actions Workflow

1. In your repository, create a file at .github/workflows/deploy.yml.

   

2. Add the following YAML configuration to automate the deployment to S3:

name: Deploy to S3

on:
  push:
    branches:
      - main

permissions:
  id-token: write
  contents: read

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Configure AWS Credentials
        uses: aws-actions/configure-aws-credentials@v2
        with:
          role-to-assume: ${{ secrets.AWS_ROLE_ARN }}
          aws-region: ${{ secrets.AWS_REGION }}

      - name: Verify AWS Role Assumption
        run: aws sts get-caller-identity

      - name: Install Dependencies
        run: npm install

      - name: Build Application
        run: npm run build

      - name: Deploy Next.js to S3
        run: |
          if [ -d "out" ]; then
            echo "✅ Found 'out/' directory (Next.js export). Deploying..."
            aws s3 sync out/ s3://${{ secrets.S3_BUCKET }}/ --delete --cache-control "public, max-age=0, must-revalidate"
          else
            echo "❌ 'out/' directory not found. Build may have failed."
            exit 1
          fi

      - name: Deploy Vite to S3
        run: |
          if [ -d "dist" ]; then
            echo "✅ Found 'dist/' directory (Vite). Deploying..."
            aws s3 sync dist/ s3://${{ secrets.S3_BUCKET }}/ --delete --cache-control "public, max-age=0, must-revalidate"
          else
            echo "❌ 'dist/' directory not found. Build may have failed."
            exit 1
          fi

Explanation of the Workflow

• Trigger: The workflow is triggered when a push is made to the main branch.

• Permissions: Grants access to the GitHub OIDC token and repository contents.

• Steps:

  1. Checkout code: Uses actions/checkout to pull the latest code.

  2. Configure AWS Credentials: Uses aws-actions/configure-aws-credentials to authenticate using the IAM role.

  3. Verify Role Assumption: Confirms that the AWS role has been assumed successfully.

  4. Install Dependencies: Runs npm install to install the necessary packages.

  5. Build Application: Executes npm run build to generate the production build.

  6. Deploy to S3: Syncs the build output (either out/ for Next.js or dist/ for Vite) to the S3 bucket, ensuring the removal of outdated files and setting proper cache headers.

Notes

• Replace placeholders: Ensure that you replace <AWS_ACCOUNT_ID>, <GITHUB_USERNAME>, <REPO_NAME>, and <BRANCH_NAME> with your actual values.

• Least-privilege policy: For production environments, use a least-privilege IAM policy instead of AdministratorAccess.

• S3 static website hosting: If you’re serving the app directly from S3, make sure your S3 bucket is configured for static website hosting