DEV Community

Camille Chang
Camille Chang

Posted on

Complete Beginner's Guide: Upload Files to AWS S3 with GitHub Actions

If you're new to GitHub Actions and AWS, this guide will walk you through automating file uploads to an S3 bucket step by step. I'll share the common mistake I made and how to fix it, so you can avoid the same pitfalls!

🎯 What We're Building

By the end of this tutorial, you'll have a GitHub Action that automatically:

  • Connects securely to your AWS account
  • Uploads files to your S3 bucket whenever you push code

📋 Prerequisites

Before we start, make sure you have:

  • A GitHub repository
  • An AWS account
  • Basic familiarity with GitHub (knowing how to create files and commit changes)

🔧 Step 1: Set Up Your S3 Bucket

First, let's create an S3 bucket where your files will be stored:

  1. Log into the AWS Console
  2. Navigate to S3
  3. Click "Create bucket"
  4. Give it a unique name (like my-project-files-bucket)
  5. Keep the default settings and create the bucket

🔐 Step 2: Create an IAM Role (The Tricky Part!)

This is where I initially got stuck, so let's break it down:

What's an IAM Role?

Think of an IAM role as a set of permissions that GitHub Actions can "borrow" to access your AWS resources. It's like giving GitHub a temporary key to your AWS account.

Creating the Role

  1. Go to IAM in AWS Console
  2. Click "Roles" → "Create role"
  3. Choose "Web identity" as the trusted entity type
  4. For Identity provider, select "OpenID Connect"
  5. Add this provider URL: token.actions.githubusercontent.com
  6. For Audience, enter: sts.amazonaws.com

Adding Permissions

Your role needs permission to upload files to S3. Attach this policy:

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

Important: Replace your-bucket-name with your actual S3 bucket name!

❌ The Problem I Ran Into

When I first tried this, I got this error:

Run aws-actions/configure-aws-credentials@v4
Configuring proxy handler for STS client
Error: Credentials could not be loaded, please check your action inputs: Could not load credentials from any providers
Enter fullscreen mode Exit fullscreen mode

The issue? I forgot the most important part - the trust policy!

✅ Step 3: Fix the Trust Policy (The Missing Piece!)

Here's what I was missing. The IAM role needs to "trust" GitHub Actions. Here's the trust policy you need:

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Effect": "Allow",
            "Principal": {
                "Federated": "arn:aws:iam::YOUR-ACCOUNT-ID:oidc-provider/token.actions.githubusercontent.com"
            },
            "Action": "sts:AssumeRoleWithWebIdentity",
            "Condition": {
                "StringEquals": {
                    "token.actions.githubusercontent.com:sub": "repo:YOUR-GITHUB-USERNAME/YOUR-REPO-NAME:ref:refs/heads/main",
                    "token.actions.githubusercontent.com:aud": "sts.amazonaws.com"
                }
            }
        }
    ]
}
Enter fullscreen mode Exit fullscreen mode

How to Apply This Trust Policy:

  1. In your IAM role, click the "Trust relationships" tab
  2. Click "Edit trust policy"
  3. Replace the existing policy with the one above
  4. Don't forget to replace:
    • YOUR-ACCOUNT-ID with your 12-digit AWS account ID
    • YOUR-GITHUB-USERNAME with your GitHub username
    • YOUR-REPO-NAME with your repository name

🔍 How to Find Your AWS Account ID

Not sure what your AWS account ID is? Here's how to find it:

  1. Click on your username in the top-right corner of AWS Console
  2. Your account ID is shown in the dropdown menu

🚀 Step 4: Create Your GitHub Action

Now create a file in your repository at .github/workflows/upload-to-s3.yml:

name: Upload to S3

on:
  push:
    branches: [ main ]

jobs:
  upload:
    runs-on: ubuntu-latest

    # This is crucial - it allows the action to get temporary credentials
    permissions:
      id-token: write
      contents: read

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

    - name: Configure AWS credentials
      uses: aws-actions/configure-aws-credentials@v4
      with:
        role-to-assume: arn:aws:iam::YOUR-ACCOUNT-ID:role/YOUR-ROLE-NAME
        aws-region: us-east-1

    - name: Upload files to S3
      run: |
        aws s3 cp ./your-file.txt s3://your-bucket-name/
Enter fullscreen mode Exit fullscreen mode

Remember to replace:

  • YOUR-ACCOUNT-ID with your AWS account ID
  • YOUR-ROLE-NAME with the name of your IAM role
  • your-bucket-name with your S3 bucket name
  • your-file.txt with the file you want to upload

🎉 Testing Your Setup

  1. Commit and push your workflow file to GitHub
  2. Go to the "Actions" tab in your GitHub repository
  3. You should see your workflow running
  4. Check your S3 bucket - your files should appear there!

📚 Want to Learn More?

Top comments (0)