Authenticating GitHub Actions to AWS using IAM Roles

Source: Dev.to

Overview

This guide shows how to authenticate GitHub Actions to AWS using an IAM role and OpenID Connect (OIDC). By using OIDC, you can eliminate long‑lived AWS access keys and avoid manual rotation.

Prerequisites

• An AWS account with sufficient IAM permissions.
• A GitHub repository where the workflow will run.

Create an OIDC Identity Provider in AWS

1. Open the IAM Console.

2. In the left navigation menu, select Identity providers.

3. Click Add provider and choose OpenID Connect as the provider type.

4. Fill in the fields:

   • Provider URL: https://token.actions.githubusercontent.com
   • Audience: sts.amazonaws.com

5. Click Add provider.

Create an IAM Role for GitHub Actions

1. In IAM, select the identity provider you just created.
2. Click Assign role → Create a new role.
3. For Trusted entity type, Web identity is pre‑selected and the identity provider field is populated.
4. In the Audience list, select sts.amazonaws.com.
5. Specify the GitHub Organization, Repository, and Branch that are allowed to assume the role, then click Next.
6. Skip adding permissions for now and click Next again.
7. On the Review page, give the role a name (e.g., GitHub-Actions-Role) and optionally a description.
8. Click Create role.

Attach an Inline S3 Policy

1. In the role’s dashboard, choose Add permissions → Create inline policy.

2. Switch the view from Visual to JSON.

3. Paste the following policy (replace your-bucket-name with your actual bucket):

   {
       "Version": "2012-10-17",
       "Statement": [
           {
               "Effect": "Allow",
               "Action": [
                   "s3:PutObject",
                   "s3:PutObjectAcl",
                   "s3:GetObject"
               ],
               "Resource": "arn:aws:s3:::your-bucket-name/*"
           }
       ]
   }

4. Click Next, name the policy (e.g., S3-permissions), and click Create policy.

GitHub Actions Workflow

Create the file .github/workflows/s3-upload.yml in your repository:

name: Upload File to S3

on:
  push:
    branches: [ main ]

env:
  AWS_REGION: us-east-1   # Change to reflect your region

jobs:
  upload:
    runs-on: ubuntu-latest

    # Allows the job to request a short‑lived OIDC token
    permissions:
      id-token: write
      contents: read

    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Configure AWS credentials
        uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::YOUR-ACCOUNT-ID:role/YOUR-ROLE-NAME
          aws-region: ${{ env.AWS_REGION }}

      - name: Upload files to S3
        run: |
          aws s3 cp ./your-file s3://your-bucket-name/

Replace the placeholders:

• YOUR-ACCOUNT-ID – your AWS account ID.
• YOUR-ROLE-NAME – the name of the IAM role you created (GitHub-Actions-Role).
• your-file – the path to the file you want to upload.
• your-bucket-name – the target S3 bucket.

Verify the Setup

After committing the workflow file, push to the main branch. The workflow should run, obtain temporary credentials via OIDC, and upload the specified file to S3.

Troubleshooting

If the workflow fails, check the following:

• The IAM role includes the required S3 permissions.
• The trust policy correctly references your GitHub organization, repository, and branch.
• The workflow job has id-token: write permission under permissions.

By following these steps, you can securely authenticate GitHub Actions to AWS without storing long‑lived access keys.