How to automate Terraform deployments with GitHub Actions.

I know… There is lots of articles on this rather basic topic. I’m not consider myself an expert. Maybe someone find helpful a HOWTO on this particular combination of technologies.

TL;DR

I’m going to create a simple workflow for deploying a Terraform stack on AWS using GitHub Action. I will setup OIDC authentication between GitHub and AWS.

Prerequisites

We will need:

a simple, working Terraform project,
an AWS account.
a GitHub account.

AWS identity provider

Please, create it according to the guide: https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws

It needs to be done once per AWS account.

S3 backend

It’s not going to work with a local state file. Let’s prepare all required items. I’m going to use Terraform code. Please mind it is not a part of the project you’re going to deploy.

Bucket

Just create a bucket with permissions.

resource "aws_s3_bucket" "state-bucket" {
  bucket = local.bucket_name
}

resource "aws_s3_bucket_versioning" "vers" {
  bucket = aws_s3_bucket.state-bucket.id
  versioning_configuration {
    status = "Enabled"
  }
}

I have a local variable describing the bucket name.

IAM

I’m going to use the same permissions for backend and for AWS provider. You probably should separate these roles for non-lab environments.

Local user

Despite - we’re going to use OIDC - I still want and user to run it locally.

data "aws_iam_policy_document" "project_policy" {
  statement {
    actions = [
      "s3:ListBucket"
    ]
    resources = [aws_s3_bucket.state-bucket.arn]
  }

  statement {
    actions = [
      "s3:GetObject",
      "s3:PutObject",
      "s3:DeleteObject"
    ]
    resources = [
      "${aws_s3_bucket.state-bucket.arn}/*/terraform.tfstate",
      "${aws_s3_bucket.state-bucket.arn}/*/terraform.tfstate.tflock"
    ]
  }
}

resource "aws_iam_user" "project_user" {
  name = "${var.project_name}-user"
}

resource "aws_iam_user_policy" "project_user_policy" {
  user   = aws_iam_user.project_user.id
  policy = data.aws_iam_policy_document.project_policy.json
}

Now - add the permissions which allow to build you infra. They are a little bit too wide. Please adjust them to your needs.

resource "aws_iam_user_policy_attachment" "ec2-full" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonEC2FullAccess"
}

resource "aws_iam_user_policy_attachment" "vpc-full" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonVPCFullAccess"
}

resource "aws_iam_user_policy_attachment" "ssm-ro" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/AmazonSSMReadOnlyAccess"
}

resource "aws_iam_user_policy_attachment" "iam-ro" {
  user       = aws_iam_user.project_user.id
  policy_arn = "arn:aws:iam::aws:policy/IAMReadOnlyAccess"
}

You will need an access key for the user to use it locally

Role

OIDC needs an IAM role.

data "aws_iam_policy_document" "sts_policy" {
  statement {
    effect = "Allow"
    principals {
      type        = "Federated"
      identifiers = ["arn:aws:iam::<AWS account ID>:oidc-provider/token.actions.githubusercontent.com"]
    }
    actions = ["sts:AssumeRoleWithWebIdentity"]
    condition {
      test     = "StringLike"
      variable = "token.actions.githubusercontent.com:sub"
      values = [
        "repo:<GitHub account>/<Repo>:ref:refs/heads/main"
      ]
    }
  }
}


resource "aws_iam_role" "project_role" {
  assume_role_policy = data.aws_iam_policy_document.sts_policy.json
  name               = "${var.project_name}-role"
}

resource "aws_iam_role_policy" "project_role_attach" {
  role   = aws_iam_role.project_role.id
  policy = data.aws_iam_policy_document.project_policy.json
}

You need to adjust the following parameters:

AWS account ID,
GitHub user or organization,
The repo name.

The last resource allows the role to access the bucket. You still need the resources access. You can copy the code from user changing aws_iam_user_policy_attachment to aws_iam_role_policy_attachment.

That’s it. You can deploy the resources manually.

Setup the S3 backend for you project

Now create or update the backend setup for your project.

terraform {
  backend "s3" {
    bucket       = "<bucket-name>"
    key          = "<stack>/terraform.tfstate"
    use_lockfile = true
    region       = "eu-central-1"
  }
}

Replace bucket name, and “folder” in the bucket. I have multiple stacks in my project - each with a separate state. If your project is live already, use terraform init -migrate-state. If i’s a fresh one - just terraform init'

Workflow setup

Crate a YAML file in .github/workflows/

---
name: Net
on:
  push:
    branches: ["main"]
    paths:
      - net/**

permissions:
  id-token: write
  contents: read

jobs:
  make_key:
    runs-on: ubuntu-latest
    defaults:
      run:
        working-directory: net/
    steps:
      - uses: actions/checkout@v6
      - uses: aws-actions/configure-aws-credentials@v5
        with:
          role-to-assume: arn:aws:iam::<AWS account id>:role/tf-infra-role
          aws-region: eu-central-1
      - uses: hashicorp/setup-terraform@v3

      - run: terraform init -input=false
      - run: terraform plan
      - run: terraform apply -auto-approve

A quick explanation:

the workflow runs when you push to the ‘main’ and something in net/ subdir is changed. As I said - I have multiple stacks with multiple workflows.
“permissions” - required to handle OIDC.
“working-directory” - skip it if you run your project in the root.
“uses: aws-actions/configure-aws-credentials” - setups AWS connectivity. Use your actual account id.
Then terraform stuff goes. I know. I should have an approval after plan…

If everything went right - after next push you infra should built. You always can run terraform destroy locally.

References

https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_create_for-idp.html

https://docs.github.com/en/actions/how-tos/secure-your-work/security-harden-deployments/oidc-in-aws