Configuring GitHub Actions To Use Terraform Workspace

I am currently enrolled in the GitOps for Terraform MiniCamp being run by Derek Morgan and Andrew Brown.

One of the tasks is to configure a GitHub Action that will run terraform and store the state file in Terraform Cloud.

This presumes you have already configured OIDC Authentication for AWS and Terraform. If not you can follow this video by Derek.

Pre-Requisites

To setup the action we require the following.

Request an API Token from Terraform Cloud
Login to Terraform in your GitHub Codespace
Storing the token in the repository with the name TF_API_TOKEN
If using environments within the repository, the secret TF_API_TOKEN needs to be set in these environments too.
Modify Terraform code to connect to the workspace
Reference the Terraform API Token within the action

Request API Token

Generate a User API token via https://app.terraform.io/app/settings/tokens

This will generate a Pop-Up Window

You can set the expiration for longer than 30 days but following best security practices it is better to have the token for a short period.

Store the generated token in a safe place as we will need it in the following steps.

From the terminal in your codespace use the following command terraform login

You will be prompted to type yes, do so.

When you type yes, codespace will try to open another browser window. As Pop-Up windows are blocked by default you will only see a black screen as shown below.

Type q to quit

Press y to confirm

Paste the API Token we generated earlier here. If successful you will see the message below with your username.

Retrieved token for user your-username


---------------------------------------------------------------------------------

                                          -                                
                                          -----                           -
                                          ---------                      --
                                          ---------  -                -----
                                           ---------  ------        -------
                                             -------  ---------  ----------
                                                ----  ---------- ----------
                                                  --  ---------- ----------
   Welcome to HCP Terraform!                       -  ---------- -------
                                                      ---  ----- ---
   Documentation: terraform.io/docs/cloud             --------   -
                                                      ----------
                                                      ----------
                                                       ---------
                                                           -----
                                                               -


   New to HCP Terraform? Follow these steps to instantly apply an example configuration:

   $ git clone https://github.com/hashicorp/tfc-getting-started.git
   $ cd tfc-getting-started
   $ scripts/setup.sh

Store the API token in the repository

We need to store the token in the repository with the name TF_API_TOKEN. We will do using the GitHub CLI.

To add a secret using the GitHub client use the following command

gh secret set secret_name

To set our secret named TF_API_TOKEN you will use the following command

gh secret set TF_API_TOKEN

Store the API Token in repository environments

To set the API token in an environment named Production use the following format
gh secret set -e environment_name secret_name

So to set TF_API_TOKEN in an environment named Production use the following command.

gh secret set -e Production TF_API_TOKEN

Modify Terraform code to connect to the workspace

Add the following code block to your Terraform configuration files to set up the cloud integration . I added this to a file called providers.tf

terraform {

  cloud {
    # The name of your Terraform Cloud organization.
    organization = "organisation_name"

    # The name of the Terraform Cloud workspace to store Terraform state files in.
    workspaces {
      name = "workspace_name"
    }
  }

  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "5.69.0"
    }
  }
}

Reference the Terraform API Token within the action

The Terraform API Token can then be referenced in an actions file with the following snippet:
${{ secrets.TF_API_TOKEN }} as shown in the snippet below where we modify the hashicorp/setup-terraform@v3 action to reference the TF_API_TOKEN secret we stored earlier.

    # Install the latest version of Terraform CLI and configure the Terraform CLI configuration file with a Terraform Cloud user API token
    - name: Setup Terraform
      uses: hashicorp/setup-terraform@v3
      with:
        cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}

Successful Output

If everything has been configured correctly you will see the following. This means that the action was able to connect successfully to the configured backend. The most important output is the coloured text.
HCP Terraform has been successfully initialized!

Error Output

If any of the above settings are not configured properly you will see the following error.

To resolve these double-check the above steps to make sure you have not missed anything and most importantly committed and pushed your changes to the repository.

References

When troubleshooting this issue I found the below resources useful.