Triggering Terraform Cloud runs from GitHub

There are two primary ways that you can trigger a run in Terraform Cloud (TFC) from code that lives in a GitHub repository, these are:

• Explicit Triggering - is when an API/CLI call triggers the TFC workspace to run. In this instance, the CI/CD tool (GitHub Actions) calls TFC via the CLI. A workspace must use the API/CLI-driven workflow to allow for explicit triggering
• Implicit Triggering - when the TFC workspace is a Version control workflow, this will automatically set up triggers for when merges occur in the repository or speculative plans when there is a pull request (PR).

Explicit Triggering#

For our example of Explicit Triggering, we will be using GitHub Actions as our executor. We will use the below GitHub Actions workflow file as our trigger for TFC.

name: 'Terraform'

on:
  push:
    branches:
      - master
  pull_request:

jobs:
  terraform:
    name: 'Terraform'
    runs-on: ubuntu-latest
    defaults:
      run:
        shell: bash
    steps:
      - name: Checkout
        uses: actions/checkout@v2
      - name: Setup Terraform
        uses: hashicorp/setup-terraform@v1
        with:
          cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}
      - name: Terraform Init
        run: terraform init
      - name: Terraform Format
        run: terraform fmt -check
      - name: Terraform Plan
        run: terraform plan
      - name: Terraform Apply
        if: github.ref == 'refs/heads/master' && github.event_name == 'push'
        run: terraform apply -auto-approve

HashiCorp provides the community a fantastic GitHub Action setup-terraform, which allows us to easily interact with TFC, Terraform Enterprise (TFE) or even Terraform Open Source (TFOS).

Now that we have our GitHub Actions workflow setup in our repository, we can set up TFC itself!

1. Head on over to your TFC instance and from the Workspaces page click on New workspace

   

2. From the Create a new Workspace page select the API-driven workflow option

   

3. Pop in the name for your workspace and click Create workspace

   

4. Once its created we will see the workspace overview page

   

5. When you push any code changes into the repository, it triggers a GitHub Actions run, which starts a workspace run in Terraform Cloud

   

6. We have pushed some code into our repository and now we can see the run in Terraform Cloud

   

In a nutshell, that is how the explicit triggering works; in this scenario, we need to trigger a run using an external tool via either the TFC API or CLI (which calls the API).

Implicit Triggering#

With implicit triggering, we will set up a workspace with the VCS-driven workflow and connect it up to a repository.

1. Login to Terraform Cloud, and from the Workspaces page click on New workspace

   

2. On the Create a new Workspace page we are going to select Version control workflow

   

3. Next we need to connect our workspace to a VCS repository, select GitHub from the available options

   

4. From the Choose a repository page, I am adding the GitHub Organisation I want to connect to by clicking on Add another organisation

   

5. GitHub will prompt us to install the Terraform Cloud GitHub App. From your list of organisations select the one you want to install the app on

   

6. On the next page, read through the permissions and click on Install

   

7. Back in TFC, we can select the repository to connect to the workspace; this is done by clicking on the repository name

   

8. Once the repository has been selected we can now click on Create workspace

   

9. After the creation is complete, you will be taken to the overview page of your workspace and are now able to queue a plan. Do this by clicking Queue plan

   

10. Once the plan finishes executing, you will see the below summary of the run and be able to apply the plan by clicking Confirm & Apply

    

11. Once the apply has finished, TFC will show you a run summary, like below. Click on the workspace name in the breadcrumbs to take us back to the workspace overview page

    

12. Now that an initial plan and apply has occurred, any subsequent changes to the repository triggers a plan. This overview page shows any resources or outputs created by the apply.

    

13. If you were to go and make a modification to any files in the repository, it would automatically trigger a plan like below

    

And that is how to implicit triggering works!