Using GitHub Actions with HashiCorp Terraform to automate infrastructure as code workflows directly from version control is a popular early path for many developer teams. However, this setup can make it difficult to stop configuration drift as your infrastructure codebase grows. <\/p>\n
Rather than running Terraform on the GitHub Actions instance runner, it\u2019s much easier and safer to run configurations remotely via HCP Terraform. This ensures that the creation, modification, and deletion of Terraform resources is handled on a managed cloud platform rather than on the GitHub Actions runner. HCP Terraform has many more systems and safeguards for team Terraform management and drift prevention<\/a>.<\/p>\n This post shows how to use HCP Terraform to define AWS infrastructure and GitHub Actions to automate infrastructure changes. You\u2019ll learn how to set up a GitHub Actions workflow that interacts with HCP Terraform to automate the deployment of AWS infrastructure, such as Amazon EC2 instances.<\/p>\n For this tutorial you can use your own Terraform configuration in a GitHub repository, or use this example repository<\/a>. The example repository\u2019s GitHub Actions include a workflow that creates the AWS resources defined in the repository. Whenever the repository trigger event happens on the main branch, it runs the workflow defined in the .github\/workflows directory. It then performs the infrastructure creation or management in AWS. The figure below outlines the interaction between the GitHub repository, Actions, HCP Terraform, and AWS.<\/p>\n Here\u2019s how to implement this workflow.<\/p>\n Ensure you have the following:<\/p>\n An AWS account with necessary permissions to create resources. Follow the following steps below to add AWS credentials in the HCP Terraform workspace and the TF_API_TOKEN in GitHub Actions secrets.<\/p>\n To allow HCP Terraform to deploy resources in AWS, you must securely provide<\/a> AWS credentials. Set the AWS access key and secret access key environment variables in your HCP Terraform workspace, ensuring that Terraform runs have the necessary permissions.<\/p>\n Please follow the steps mentioned in the official documentation<\/a> to add the AWS credentials into HCP Terraform.<\/p>\n Fetch the TF_API_TOKEN by following instructions available in the HCP Terraform documentation<\/a>. This example creates a user API token for the GitHub Action workflow.<\/p>\n Open the GitHub repository with the Terraform configuration.<\/p>\n Click on “Settings” in the repository menu. From the left sidebar, select “Secrets” and then choose “Actions”.<\/p>\n To add a new repository secret, click on “New repository secret”. Name the secret TF_API_TOKEN and add the HCP Terraform API token to the \u201cValue\u201d field. Click “Add secret” to save the new secret.<\/p>\n By following these steps, you will securely provide your AWS credentials to HCP Terraform and also provide the HCP Terraform API token to GitHub Actions, enabling automated infrastructure deployment through a GitHub Actions workflow.<\/p>\n After setting up the credentials, add a GitHub Actions workflow to your repository. The example repository uses a workflow<\/a> YAML file defining one job with four steps to initialize, plan, apply, and destroy Terraform. This workflow uses the HashiCorp official marketplace actions<\/a> for performing the Terraform command operations.<\/p>\n # This workflow will create AWS resource using HCP Terraform name: AWS Infra Creation Using in HCP Terraform<\/p>\n on: env: jobs: runs-on: ubuntu-latest<\/p>\n steps: # Configure Terraform cloud API token, since we are using Remote backend option of Terraform cloud in AWS code # Add the AWS Creds as ENV variable in HCP Terraform workspace, since the tf run happens in HCP Terraform environment<\/p>\n # Invoke the Terraform commands echo “** Running Terraform Validate**” – name: Terraform Plan – name: Terraform Plan Output – name: Reference Plan Output # Once the user verifies the Terraform Plan, the user can run the Terraform Apply and Destroy commands # Invoke the Terraform commands echo “** Running Terraform Validate**” – name: Terraform Apply Let\u2019s review each section of the workflow.<\/p>\n When you push commits or open a pull request on the main branch, the workflow initializes, plans, and applies Terraform. This workflow can be triggered by a:<\/p>\n workflow_call: This allows the workflow to be reused in other workflows. It requires the TF_API_TOKEN secret. # This workflow will create AWS resource using HCP Terraform name: AWS Infra Creation Using in HCP Terraform<\/p>\n on: Set the tfcode_path environment variable to specify the location of your Terraform configuration files within the repository. Include the HCP Terraform organization, workspace, and hostname for future jobs.<\/p>\n env: In the GitHub Actions workflow, define each automation step inside the jobs block. The job consists of job name and workflow runner instance definition in the runs-on block. This workflow uses the ubuntu-latest instance runner.<\/p>\n The first step in the apply_terraform_plan is the actions\/checkout entry, which clones the repository into the GitHub Actions runner. This makes the Terraform configuration files available for subsequent steps.<\/p>\n jobs: runs-on: ubuntu-latest<\/p>\n steps: In the second step, use the hashicorp\/setup-terraform pre-built action to configure the Terraform CLI in the runner environment. It sets up the HCP Terraform API token (TF_API_TOKEN) for authentication. This token allows the Terraform CLI to communicate with HCP Terraform, enabling it to manage state, perform operations, and apply configurations in the context of the HCP Terraform workspace.<\/p>\n – name: Setup Terraform CLI Next, initialize and validate Terraform. terraform init initializes the Terraform working directory by downloading necessary providers and initializing backends. If you\u2019re using HCP Terraform as the backend, this command configures the workspace and prepares it for operations. <\/p>\n terraform validate checks the syntax and validity of the Terraform files, ensuring they are correctly formatted and logically sound. These commands run inside the working directory defined by env.tfcode_path, which contains the Terraform configuration.<\/p>\n – name: Terraform init and validate echo “** Running Terraform Validate**” In general, you will want to review theterraform plan before applying to verify the changes Terraform will make. Use the hashicorp\/tfc-workflows-github\/actions\/create-run action to run a plan in HCP Terraform and export the plan using the plan_only attribute. Then, use the hashicorp\/tfc-workflows-github\/actions\/plan-output action to get the output of the Terraform plan using the plan_id from the previous step’s output. Finally, print the plan status and resource changes in the workflow\u2019s output.<\/p>\n – name: Terraform Plan – name: Terraform Plan Output – name: Reference Plan Output The workflow outputs the plan status and any resources to add, change, or destroy in its log.<\/p>\n If the plan does not reflect the correct changes, fix the Terraform configuration to achieve the expected output. After verifying the plan in the previous job, manually trigger the workflow to run terraform apply. This command starts a run in the HCP Terraform workspace, where the actual infrastructure changes are made.<\/p>\n apply_terraform_plan: # Invoke the Terraform commands echo “** Running Terraform Validate**” – name: Terraform Apply Optionally, you can add a terraform destroy step to clean up resources and avoid unnecessary costs. You can add this step in non-production or testing environments.<\/p>\n – name: Terraform Destroy This setup leverages the strengths of both platforms: GitHub Actions for CI\/CD automation and HCP Terraform for secure, collaborative infrastructure management. Integrating HCP Terraform with GitHub Actions provides a powerful, automated pipeline for deploying and managing AWS infrastructure. By leveraging these tools, teams can achieve more reliable and efficient infrastructure management, reduce manual errors, and ensure consistency across environments. <\/p>\n HCP Terraform facilitates collaboration among team members ensuring that infrastructure changes are managed safely and efficiently. Platform teams can audit the runs in HCP Terraform while development teams can review runs in GitHub Actions.<\/p>\n From a security perspective, HCP Terraform workspaces can be configured with environment variables, such as AWS credentials, or dynamic credentials<\/a>. The GitHub Actions workflow does not directly handle the credentials, which minimizes the blast radius of compromised credentials through the workflow. HCP Terraform provides additional features like access controls, private module registry, and policy enforcement to ensure that infrastructure changes are secure and compliant with organizational policies. <\/p>\n This guide has walked you through setting up a basic workflow, but the flexibility of both platforms allows for customization to fit your specific needs.<\/p>\n For further questions on best practices, please refer to the GitHub Actions and HCP Terraform FAQs available in this repository<\/a>. As mentioned before, this repository includes the full code example used in this post. For more information on GitHub Actions, review GitHub\u2019s documentation<\/a>. To learn more about automating Terraform with GitHub Actions, review the official tutorial<\/a> on the HashiCorp Developer portal and the starter workflow templates<\/a> to use HCP Terraform with GitHub Actions.<\/p>\nWorkflow overview<\/h2>\n
Prerequisites<\/h2>\n
\nA HCP Terraform account, with a workspace set up for this tutorial.
\nA GitHub account, with a repository for Terraform configuration files.
\nThe Terraform CLI installed on your local machine for testing purposes.<\/p>\nAdd AWS credentials to HCP Terraform<\/h2>\n
Add HCP Terraform token to GitHub Actions<\/h2>\n
Create the GitHub Actions workflow<\/h2>\n
\n# It is reusable workflow that can be called in other workflows<\/p>\n
\n workflow_call:
\n secrets:
\n TF_API_TOKEN:
\n required: true
\n push:
\n branches: [ “main” ]
\n pull_request:
\n branches: [ “main” ]
\n workflow_dispatch:<\/p>\n
\n tfcode_path: tfcloud_samples\/amazon_ec2
\n tfc_organisation: demo-tf-org # Replace it with your TFC Org
\n tfc_hostname: app.terraform.io
\n tfc_workspace: demo-tf-workspace # Replace it with your TFC Workspace<\/p>\n
\n aws_tfc_job:
\n name: Create AWS Infra Using TFC<\/p>\n
\n – name: Checkout tf code in runner environment
\n uses: actions\/checkout@v3.5.2<\/p>\n
\n – name: Setup Terraform CLI
\n uses: hashicorp\/setup-terraform@v2.0.2
\n with:
\n cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}<\/p>\n
\n – name: Terraform init and validate
\n run: |
\n echo `pwd`
\n echo “** Running Terraform Init**”
\n terraform init<\/p>\n
\n terraform validate
\n working-directory: ${{ env.tfcode_path }}<\/p>\n
\n uses: hashicorp\/tfc-workflows-github\/actions\/create-run@v1.3.0
\n id: run
\n with:
\n workspace: ${{ env.tfc_workspace }}
\n plan_only: true
\n message: “Plan Run from GitHub Actions”
\n ## Can specify hostname,token,organization as direct inputs
\n hostname: ${{ env.tfc_hostname }}
\n token: ${{ secrets.TF_API_TOKEN }}
\n organization: ${{ env.tfc_organisation }}<\/p>\n
\n uses: hashicorp\/tfc-workflows-github\/actions\/plan-output@v1.3.0
\n id: plan-output
\n with:
\n hostname: ${{ env.tfc_hostname }}
\n token: ${{ secrets.TF_API_TOKEN }}
\n organization: ${{ env.tfc_organisation }}
\n plan: ${{ steps.run.outputs.plan_id }}<\/p>\n
\n run: |
\n echo “Plan status: ${{ steps.plan-output.outputs.plan_status }}”
\n echo “Resources to Add: ${{ steps.plan-output.outputs.add }}”
\n echo “Resources to Change: ${{ steps.plan-output.outputs.change }}”
\n echo “Resources to Destroy: ${{ steps.plan-output.outputs.destroy }}”<\/p>\n
\n apply_terraform_plan:
\n needs: aws_tfc_job
\n if: github.event_name == ‘workflow_dispatch’
\n runs-on: ubuntu-latest
\n steps:
\n – name: Checkout
\n uses: actions\/checkout@v3.5.2
\n – name: Setup Terraform CLI
\n uses: hashicorp\/setup-terraform@v2.0.2
\n with:
\n cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}<\/p>\n
\n – name: Terraform init and validate
\n run: |
\n echo `pwd`
\n echo “** Running Terraform Init**”
\n terraform init<\/p>\n
\n terraform validate
\n working-directory: ${{ env.tfcode_path }}<\/p>\n
\n run: echo “** Running Terraform Apply**”; terraform apply -auto-approve
\n working-directory: ${{ env.tfcode_path }}
\n – name: Terraform Destroy
\n run: echo “** Running Terraform Destroy**”; terraform destroy -auto-approve
\n working-directory: ${{ env.tfcode_path }}<\/p>\nDefine the triggers<\/h3>\n
\npush: Triggers the workflow when there is a push to the main branch.
\npull_request: Triggers the workflow when a pull request is made to the main branch.
\nworkflow_dispatch: Allows the GitHub Actions interface to manually trigger the workflow.<\/p>\n
\n# It is reusable workflow that can be called in other workflows<\/p>\n
\n workflow_call:
\n secrets:
\n TF_API_TOKEN:
\n required: true
\n push:
\n branches: [ “main” ]
\n pull_request:
\n branches: [ “main” ]
\n workflow_dispatch:<\/p>\nConfigure environment variables<\/h3>\n
\n tfcode_path: tfcloud_samples\/amazon_ec2 # Directory in which the tf files are stored
\n tfc_organisation: demo-tf-org # Replace it with your TFC Org
\n tfc_hostname: app.terraform.io
\n tfc_workspace: demo-tf-workspace # Replace it with your TFC Workspace<\/p>\nDefine jobs<\/h3>\n
\n aws_tfc_job:
\n name: Create AWS Infra Using HCPTF<\/p>\n
\n – name: Checkout tf code in runner environment
\n uses: actions\/checkout@v3.5.2<\/p>\n
\n uses: hashicorp\/setup-terraform@v2.0.2
\n with:
\n cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}<\/p>\n
\n run: |
\n echo `pwd`
\n echo “** Running Terraform Init**”
\n terraform init<\/p>\n
\n terraform validate
\n working-directory: ${{ env.tfcode_path }}<\/p>\n
\n uses: hashicorp\/tfc-workflows-github\/actions\/create-run@v1.3.0
\n id: run
\n with:
\n workspace: ${{ env.tfc_workspace }}
\n plan_only: true
\n message: “Plan Run from GitHub Actions”
\n hostname: ${{ env.tfc_hostname }}
\n token: ${{ secrets.TF_API_TOKEN }}
\n organization: ${{ env.tfc_organisation }}<\/p>\n
\n uses: hashicorp\/tfc-workflows-github\/actions\/plan-output@v1.3.0
\n id: plan-output
\n with:
\n hostname: ${{ env.tfc_hostname }}
\n token: ${{ secrets.TF_API_TOKEN }}
\n organization: ${{ env.tfc_organisation }}
\n plan: ${{ steps.run.outputs.plan_id }}<\/p>\n
\n run: |
\n echo “Plan status: ${{ steps.plan-output.outputs.plan_status }}”
\n echo “Resources to Add: ${{ steps.plan-output.outputs.add }}”
\n echo “Resources to Change: ${{ steps.plan-output.outputs.change }}”
\n echo “Resources to Destroy: ${{ steps.plan-output.outputs.destroy }}”<\/p>\n
\n needs: aws_tfc_job
\n if: github.event_name == ‘workflow_dispatch’
\n runs-on: ubuntu-latest
\n steps:
\n – name: Checkout
\n uses: actions\/checkout@v3.5.2
\n – name: Setup Terraform CLI
\n uses: hashicorp\/setup-terraform@v2.0.2
\n with:
\n cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}<\/p>\n
\n – name: Terraform init and validate
\n run: |
\n echo `pwd`
\n echo “** Running Terraform Init**”
\n terraform init<\/p>\n
\n terraform validate
\n working-directory: ${{ env.tfcode_path }}<\/p>\n
\n run: echo “** Running Terraform Apply**”; terraform apply -auto-approve
\n working-directory: ${{ env.tfcode_path }}<\/p>\n
\n run: |
\n echo “** Running Terraform Destroy**”
\n terraform destroy -auto-approve
\n working-directory: ${{ env.tfcode_path }}<\/p>\nSetup review and further learning<\/h2>\n