AWS Learning Journey

GitHub Actions + AWS: The Complete Guide for Real Deployments

Workflow syntax, runners, variables and secrets, environments and approvals, reusable workflows, matrix builds, artifacts, caching, OIDC, Docker, ECS, and S3 + CloudFront deployments — and how to keep it all secure.

8 min read · 1487 words
GitHub ActionsAWSCI/CDDevOpsDevSecOps
GitHub Actions + AWS: The Complete Guide for Real Deployments cover image

AWS from Zero to Production — Phase 7, Part 2 of 5 · See the full series roadmap


GitHub Actions is probably the most common way teams deploy to AWS today. It lives next to your code, it’s free to start, and there’s an action for almost everything.

It’s also easy to get wrong in ways that matter: long-lived AWS keys stored as secrets, workflows that any pull request can trigger with production credentials, third-party actions pulled from a moving tag, and jobs with far more permissions than they need.

This article covers the whole toolkit — and the security habits that should come with it. In Phase 2, you deployed to S3 with OIDC. Here, you’ll see the bigger picture, before building a complete pipeline in Part 5.

What you’ll walk away with


Workflow syntax

Workflows are YAML files in .github/workflows/:

name: ci

on:
  pull_request:
  push:
    branches: [main]

permissions:
  contents: read

concurrency:
  group: ci-${{ github.ref }}
  cancel-in-progress: true

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - uses: actions/setup-python@v6
        with:
          python-version: "3.12"
          cache: pip
      - run: pip install -r requirements.txt -r requirements-dev.txt
      - run: pytest -q

  build:
    needs: test
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5
      - run: docker build -t orders-api:${{ github.sha }} .

Runners

A runner is the machine that executes a job.

GitHub-hosted runners

Self-hosted runners

Warning: Never use self-hosted runners on public repositories. Anyone can open a pull request that runs code on your machine. For private repositories, use ephemeral runners that are destroyed after each job.


Variables and secrets

env:
  AWS_REGION: ${{ vars.AWS_REGION }}

With OIDC, you don’t need AWS secrets at all. The role ARN isn’t sensitive — the trust policy decides who can use it.


GitHub Environments and approvals

A GitHub Environment — like staging or production — adds controls to jobs that target it:

deploy-prod:
  needs: deploy-staging
  runs-on: ubuntu-latest
  environment: production
  steps:
    - run: echo "Deploying..."

And, as you saw in Phase 2, the OIDC token’s sub claim includes the environment name — so your AWS trust policy can allow only the production environment to assume the production role.


Reusable workflows

Don’t copy the same deploy steps into every repository. Define them once:

# .github/workflows/deploy-ecs.yml  (in a shared repository)
on:
  workflow_call:
    inputs:
      environment:
        type: string
        required: true
      image:
        type: string
        required: true

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: ${{ inputs.environment }}
    permissions:
      id-token: write
      contents: read
    steps:
      - run: echo "Deploying ${{ inputs.image }} to ${{ inputs.environment }}"

Call it from any repository:

jobs:
  prod:
    uses: acme/platform-workflows/.github/workflows/deploy-ecs.yml@v3
    with:
      environment: production
      image: ${{ needs.build.outputs.image }}

Composite actions are the smaller-scale equivalent: a reusable bundle of steps, rather than whole jobs.


Matrix builds

Run the same job across combinations:

test:
  runs-on: ${{ matrix.os }}
  strategy:
    fail-fast: false
    matrix:
      os: [ubuntu-latest, ubuntu-24.04-arm]
      python: ["3.12", "3.13"]
  steps:
    - uses: actions/checkout@v5
    - uses: actions/setup-python@v6
      with:
        python-version: ${{ matrix.python }}
    - run: pytest -q

That’s four jobs from one definition — handy for testing libraries across versions and architectures.


Artifacts and caching

- uses: actions/upload-artifact@v4
  with:
    name: test-report
    path: reports/

Don’t confuse them: Artifacts are outputs you want to keep or pass on. Caches are speed-ups that may disappear at any time.


OIDC authentication to AWS

The pattern from Phase 2, in its minimal form:

permissions:
  id-token: write
  contents: read

steps:
  - uses: aws-actions/configure-aws-credentials@v6
    with:
      role-to-assume: ${{ vars.AWS_ROLE_ARN }}
      aws-region: ${{ vars.AWS_REGION }}
  - run: aws sts get-caller-identity

Docker build and push to ECR

- uses: aws-actions/amazon-ecr-login@v2
  id: ecr

- uses: docker/setup-buildx-action@v3

- uses: docker/build-push-action@v6
  with:
    context: .
    platforms: linux/amd64
    push: true
    tags: ${{ steps.ecr.outputs.registry }}/orders:${{ github.sha }}
    cache-from: type=gha
    cache-to: type=gha,mode=max

The commit SHA becomes the image tag — immutable and traceable back to the exact code.


ECS deployment

The AWS-maintained actions render a new task definition and deploy it:

- run: |
    aws ecs describe-task-definition --task-definition orders-dev \
      --query taskDefinition > taskdef.json

- uses: aws-actions/amazon-ecs-render-task-definition@v1
  id: render
  with:
    task-definition: taskdef.json
    container-name: orders
    image: ${{ steps.ecr.outputs.registry }}/orders:${{ github.sha }}

- uses: aws-actions/amazon-ecs-deploy-task-definition@v2
  with:
    task-definition: ${{ steps.render.outputs.task-definition }}
    cluster: orders-dev
    service: orders
    wait-for-service-stability: true

wait-for-service-stability makes the job fail if the new tasks never become healthy — and with the ECS circuit breaker enabled, the service rolls itself back.


S3 and CloudFront deployment

For a static front end:

- run: npm ci && npm run build

- run: |
    aws s3 sync dist/ "s3://${{ vars.SITE_BUCKET }}/" --delete \
      --exclude index.html --cache-control "public,max-age=31536000,immutable"
    aws s3 cp dist/index.html "s3://${{ vars.SITE_BUCKET }}/index.html" \
      --cache-control "no-cache"

- run: |
    aws cloudfront create-invalidation \
      --distribution-id "${{ vars.CF_DISTRIBUTION_ID }}" \
      --paths "/index.html"

Hashed asset files are cached for a year; index.html is always revalidated. Only index.html needs invalidating.


Hardening your workflows

# Risky
- run: echo "${{ github.event.pull_request.title }}"

# Safer
- env:
    PR_TITLE: ${{ github.event.pull_request.title }}
  run: echo "$PR_TITLE"

Common mistakes


Key takeaways


Quick self-check

Test yourself before moving on:

  1. Which permission does a job need to request an OIDC token?
  2. Should the AWS role ARN be a variable or a secret?
  3. Why pin third-party actions to a commit SHA?
  4. What does wait-for-service-stability add to an ECS deployment?

Answers

  1. id-token: write.
  2. A variable — it isn’t sensitive; the trust policy controls access.
  3. Tags can be moved to malicious code; a commit SHA can’t.
  4. The job fails if the new tasks don’t become stable and healthy.

What’s next

In Part 3, we look at the AWS-native alternative: CodeBuild, CodeDeploy, and CodePipeline — including blue-green deployments for ECS and traffic shifting for Lambda.

What’s the one GitHub Actions trick that saved your team the most time? Share it in the comments.


Share this article

LinkedIn post draft