Automate Terraform with GitHub Actions

11min
|
HCP Terraform
Terraform

GitHub Actions add continuous integration to GitHub repositories to automate your software builds, tests, and deployments. Automating Terraform with CI/CD enforces configuration best practices, promotes collaboration, and automates the Terraform workflow.

HashiCorp provides GitHub Actions that integrate with the HCP Terraform API. These actions let you create your own custom CI/CD workflows to meet the needs of your organization.

In this tutorial, you will use HashiCorp's HCP Terraform GitHub Actions to create a complete Actions workflow to deploy a publicly accessible web server within an HCP Terraform workspace.

HCP Terraform and GitHub Actions Workflow

The workflow will:

Generate a plan for every commit to a pull request branch, which you can review in HCP Terraform.
Apply the configuration when you update themain branch.

After configuring the GitHub Action, you will create and merge a pull request to test the workflow.

HCP Terraform's built-in support for GitHub webhooks can accomplish this generic workflow. However, by using HashiCorp's HCP Terraform GitHub Actions, you can create a custom workflow with additional steps before or after your Terraform operations.

Prerequisites

This tutorial assumes that you are familiar with the Terraform and HCPTerraform workflows. If you are new to Terraform, complete theGet Startedtutorials first. If you are new toHCP Terraform, complete theHCP Terraform Get Startedtutorials first.

For this tutorial, you will need:

Note

This tutorial will provision resources that qualify under theAWS free-tier. If your account doesn't qualify under the AWS free-tier, we are not responsible for any charges that you may incur.

Create an HCP Terraform team token

Navigate to your organization's settings page and clickTeams. ClickCreate a team and specifyGitHub Actions in theTeam name field. Leave all permissions set to their default values.

Next, navigate to theAPI tokens page in your organization's settings, clickTeam Tokens, and then clickCreate a team token.

Choose yourGitHub Actions team, leave theExpiration set to the default value of30 days, then clickCreate.

Save this token in a safe place. You will add it to GitHub later as a secret, so the Actions workflow can authenticate to HCP Terraform.

Create the HCP Terraform workspace

The GitHub Action you create will connect to HCP Terraform to plan and apply your configuration. Before you set up the Actions workflow, you must create a workspace and add your AWS credentials as workspace variables.

First, create a new HCP Terraform workspace namedlearn-terraform-github-actions.

Go to theCreate a new Workspace page and selectAPI-driven workflow.

Name your workspacelearn-terraform-github-actions and clickCreate workspace.

Now, find the AWS credentials you want to use for the workspace, or create a new key pair in theIAM console. On your workspace's overview page clickVariables in the left navigation bar. Then, add the following asEnvironment Variables for yourlearn-terraform-github-actions workspace.

Type	Variable name	Description	Sensitive
Environment variable	`AWS_ACCESS_KEY_ID`	The access key ID from your AWS key pair	No
Environment variable	`AWS_SECRET_ACCESS_KEY`	The secret access key from your AWS key pair	Yes

Tip

If you have temporary AWS credentials, you must also add yourAWS_SESSION_TOKEN as an environment variable.

HCP Terraform will use these credentials to authenticate to AWS.

Assign AWS Credentials as HCP Terraform workspace environment variables.

Tip

This tutorial uses IAM user authentication. You can use any authentication method described in theAWS provider documentation.

Next, give your GitHub Actions team permission to run plan and apply runs in this workspace. Navigate to the workspace'sSettings page, clickTeam Access, then clickAdd team and permissions.

On the next page, chooseGitHub Actions from theTeam dropdown, choose theWrite permission group, then clickUpdate permissions.

Set up a GitHub repository

In your browser, navigate to theLearn Terraform GitHub Actions template repository.

SelectUse this template, then selectCreate a new repository.

Create new repository from template

In theOwner dropdown, select your personal GitHub account.

Next, enterlearn-terraform-github-actions as theRepository name.

Finally, selectPublic and clickCreate repository from template.

In your new repository, navigate to theSettings page. Open theSecrets and variables menu, then selectActions.

Open actions secrets and variables page in settings

Now, selectNew repository secret. Create a secret namedTF_API_TOKEN, setting the HCP Terraform API token you created in the previous step as the value.

Then, clone your forked repository to your local machine. Remember to replaceYOUR-USER-NAME with your GitHub username if you are using the command below.

$ git clone git@github.com:YOUR-USER-NAME/learn-terraform-github-actions

Review Actions workflows

There are several files in your local repository.

main.tf contains Terraform configuration to deploy a publicly accessible EC2 instance.
.github/workflows/terraform-plan.yml defines the Actions workflow that runs Terraform plan.
.github/workflows/terraform-apply.yml defines the Actions workflow that runs Terraform apply.