How to Deploy a CloudFormation Stack With GitHub Actions

Run aws cloudformation deploy, which creates a change set and applies it, creating or updating the stack idempotently.

aws cloudformation deploy handles create-or-update in one command. Pass --template-file, --parameter-overrides, and --capabilities when the template provisions IAM resources.

Steps

• Authenticate to AWS over OIDC.
• Validate the template with aws cloudformation validate-template (optional).
• Run aws cloudformation deploy with the stack name and template.
• Pass --parameter-overrides and --capabilities as needed.

Workflow

permissions:
  id-token: write
  contents: read
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: aws-actions/configure-aws-credentials@v4
        with:
          role-to-assume: arn:aws:iam::123456789012:role/gha-cfn-deploy
          aws-region: us-east-1
      - run: |
          aws cloudformation deploy \
            --stack-name my-stack \
            --template-file infra/template.yml \
            --parameter-overrides Env=prod ImageTag=${{ github.sha }} \
            --capabilities CAPABILITY_IAM \
            --no-fail-on-empty-changeset

Gotchas

• --no-fail-on-empty-changeset avoids a nonzero exit when nothing changed.
• A stack stuck in ROLLBACK_COMPLETE cannot be updated; delete and recreate it.

Related guides