Setting up Centralized Terraform State with GitHub Actions

The following is an example of using Github Actions with infrastructure as code to Terraform to give you a quick and easy CI/CD solution.

GitHub Actions is a feature offered by GitHub, enabling users to automate, customize, and execute software development workflows directly within their GitHub repositories. It allows building, testing, and deploying code straight from GitHub. Additionally, GitHub Actions facilitates the setup of a Continuous Integration (CI) and Continuous Deployment (CD) pipeline.

Some key aspects of GitHub Actions include:

  1. Workflows: These are the automated processes that you can set up for your repository. Workflows are made up of one or more jobs and can be scheduled or triggered by specific events.

  2. Events: A workflow can be started by various GitHub events, such as a push or pull request. You can also schedule workflows to run at specified times using cron syntax.

  3. Jobs: A workflow run is made up of one or more jobs. Jobs run in parallel by default, but they can be configured to depend on one another.

  4. Steps: Each job consists of a series of steps. Steps can run commands, run setup tasks, or run an action in your repository, a public repository, or an action published in a Docker registry.

  5. Actions: These are individual tasks that you plug into a workflow. You can create your own actions or use actions shared by the GitHub community.

  6. Runners: Workflows run on hosted virtual machines, or you can host your own runners to run jobs. GitHub offers runners for Linux, Windows, and macOS, but you can also use a custom runner for specific environments.

  7. Secrets: For security reasons, you might need to keep certain information, like API keys or credentials, out of your workflows. Secrets allow you to store sensitive information while making it accessible to your workflows.

  8. Artifacts: After a workflow completes, you can save files (like build outputs) that can be used by subsequent jobs or stored for future reference.

One common use of GitHub Actions is establishing a CI/CD pipeline to automate the build and deployment process. For example, every time code is pushed to the main branch, an action could run tests, build the code, and then deploy it to a staging or production server.

Overall, GitHub Actions offer flexibility and integration to help teams and individuals automate any task or process related to their software projects.

When automating Terraform with CI/CD, it enforces configuration best practices, promotes collaboration, and automates the Terraform workflow. In this blog, I will guide you through the process of creating an AWS S3 website using both Terraform and GitHub Actions.

The aim of this guide is to establish a centralized location for Terraform state files, which will then be automatically applied via GitHub Actions whenever you push changes to your GitHub repository.


  • An active AWS account.

  • Git installed on your local machine.

  • A GitHub account.

  • A GitHub repository where your Terraform code will reside.

  • Terraform binary installed.

Setup Guide

1. Backend Bucket Creation

The initial phase involves creating an S3 bucket on AWS to serve as the backend for your Terraform state files.


  1. Clone the Repository:
    Use the following command to clone the repository to your local machine:
git clone
  1. Set AWS Credentials Locally:
    Ensure you have your AWS credentials set up in your environment, so Terraform can interact with AWS services.
export AWS_ACCESS_KEY_ID=<your-access-key-id>
export AWS_SECRET_ACCESS_KEY=<your-secret-access-key>
  1. Initialize Terraform:
    Navigate to the cloned repository's directory and run:
terraform init
  1. Update Bucket Name:
    Edit the file. Find the bucket properties in both the backend configuration and the S3 resource blocks. Update them with your desired S3 bucket name.

  2. Apply Terraform Configuration:
    Run the following command and confirm by typing yes when prompted:

terraform apply

2. Setting Up Terraform with GitHub Actions

Once the backend is set up, you'll configure GitHub Actions to automatically apply your Terraform configurations whenever there's a change.


  1. Enable Backend Configuration:
    Go back to the file and uncomment (remove the # symbols) the backend configuration section.

  2. Re-initialize Terraform:
    As you've made changes to the backend configuration, you'll need to re-initialize Terraform:

terraform init

When prompted, type yes to confirm the move of your state to the new backend location.

  1. Store AWS Credentials in GitHub:
    For GitHub Actions to interact with AWS on your behalf, it needs your AWS credentials. Store them as secrets in your GitHub repository:
  • Navigate to your repository on GitHub.

  • Go to the 'Settings' tab.

  • Under the left sidebar, click on 'Secrets'.

  • Click the 'New repository secret' button.

  • Add both AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY with their respective values.

  1. Commit Changes:
    Commit any changes made to your Terraform files:
git add .
git commit -m "First commit with backend configuration"
  1. Push to GitHub:
    Push your changes to the remote GitHub repository:
git push

After completing these steps, your Terraform configurations will be set up to use a centralized state stored in an AWS S3 bucket. Additionally, using GitHub Actions, every push you make to this repository will trigger Terraform actions (e.g., terraform apply) based on your configurations. Ensure that you set up a .github/workflows/ directory in your repository with the necessary GitHub Actions configurations for Terraform.

Did you find this article valuable?

Support Sebastian Maniak by becoming a sponsor. Any amount is appreciated!