» Getting Started

GitHub Actions allow you to trigger commands in reaction to GitHub events. Terraform's GitHub Actions are designed to run on new and updated pull requests to help you review and validate Terraform changes.

The easiest way to get started is to copy our recommended workflow, which runs all of Terraform's GitHub Actions on new and updated pull requests.

  1. Open up your repository in GitHub and click on the Actions tab.

    Actions Tab

  2. Click the Create a new workflow button.

    Create a new workflow

  3. Click the <> Edit new file tab.

    Edit Workflow Tab

  4. Replace the default workflow with the following:

    workflow "Terraform" {
      resolves = "terraform-plan"
      on = "pull_request"
    }
    
    action "filter-to-pr-open-synced" {
      uses = "actions/bin/filter@master"
      args = "action 'opened|synchronize'"
    }
    
    action "terraform-fmt" {
      uses = "hashicorp/terraform-github-actions/fmt@v<latest version>"
      needs = "filter-to-pr-open-synced"
      secrets = ["GITHUB_TOKEN"]
      env = {
        TF_ACTION_WORKING_DIR = "."
      }
    }
    
    action "terraform-init" {
      uses = "hashicorp/terraform-github-actions/init@v<latest version>"
      needs = "terraform-fmt"
      secrets = ["GITHUB_TOKEN"]
      env = {
        TF_ACTION_WORKING_DIR = "."
      }
    }
    
    action "terraform-validate" {
      uses = "hashicorp/terraform-github-actions/validate@v<latest version>"
      needs = "terraform-init"
      secrets = ["GITHUB_TOKEN"]
      env = {
        TF_ACTION_WORKING_DIR = "."
      }
    }
    
    action "terraform-plan" {
      uses = "hashicorp/terraform-github-actions/plan@v<latest version>"
      needs = "terraform-validate"
      secrets = ["GITHUB_TOKEN"]
      env = {
        TF_ACTION_WORKING_DIR = "."
        # If you're using Terraform workspaces, set this to the workspace name.
        TF_ACTION_WORKSPACE = "default"
      }
    }
    
  5. Find the latest version from https://github.com/hashicorp/terraform-github-actions/releases and replace all instances of @v<latest version>. For example: uses = "hashicorp/terraform-github-actions/plan@v3.0".

  6. Directories — If your Terraform configuration is not in the root of your repo, replace all instances of:

    TF_ACTION_WORKING_DIR = "."
    

    ...with your directory, relative to the root of the repo. For example:

    TF_ACTION_WORKING_DIR = "./terraform"
    

    If you have multiple directories of Terraform code, see Directories.

  7. Workspaces — If your Terraform runs in a different Terraform workspace than default, change the TF_ACTION_WORKSPACE environment variable in the terraform-plan action.

    TF_ACTION_WORKSPACE = "your-workspace"
    

    If you have multiple workspaces, see Workspaces.

  8. Credentials — If you're using a Terraform provider that requires credentials to run terraform init and terraform plan (like AWS or Google Cloud Platform) then you need to add those credentials as secrets to the terraform-init and terraform-plan actions. Secrets can be added from the Visual Editor, so switch to that tab.

    Visual Editor

    Scroll down to the terraform-init or terraform-plan actions and click Edit. This will open the action editor on the right side, where you'll be able to add your secrets as environment variables, like AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. See your provider documentation for the specific environment variables your provider needs. If you've already added these secrets to the repository, they will be available for selection.

    Add Secrets

  9. Click Start commit to commit the Workflow.

  10. On your next pull request, you should see the Actions running.