search

hashicorp / setup-terraform

Sets up Terraform CLI in your GitHub Actions workflow.
https://developer.hashicorp.com/terraform/tutorials/automation/github-actions
Mozilla Public License 2.0
1.38k stars 243 forks source link

readme

setup-terraform

Continuous Integration Setup Terraform

The hashicorp/setup-terraform action is a JavaScript action that sets up Terraform CLI in your GitHub Actions workflow by:

After you've used the action, subsequent steps in the same job can run arbitrary Terraform commands using the GitHub Actions run syntax. This allows most Terraform commands to work exactly like they do on your local command line.

Usage

This action can be run on ubuntu-latest, windows-latest, and macos-latest GitHub Actions runners. When running on windows-latest the shell should be set to Bash. When running on self-hosted GitHub Actions runners, NodeJS must be previously installed with the version specified in the action.yml.

The default configuration installs the latest version of Terraform CLI and installs the wrapper script to wrap subsequent calls to the terraform binary:

steps:
- uses: hashicorp/setup-terraform@v3

A specific version of Terraform CLI can be installed:

steps:
- uses: hashicorp/setup-terraform@v3
  with:
    terraform_version: "1.1.7"

Credentials for HCP Terraform (app.terraform.io) can be configured:

steps:
- uses: hashicorp/setup-terraform@v3
  with:
    cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}

Credentials for Terraform Enterprise (TFE) can be configured:

steps:
- uses: hashicorp/setup-terraform@v3
  with:
    cli_config_credentials_hostname: 'terraform.example.com'
    cli_config_credentials_token: ${{ secrets.TF_API_TOKEN }}

The wrapper script installation can be skipped by setting the terraform_wrapper variable to false:

steps:
- uses: hashicorp/setup-terraform@v3
  with:
    terraform_wrapper: false

Subsequent steps can access outputs when the wrapper script is installed:

steps:
- uses: hashicorp/setup-terraform@v3

- run: terraform init

- id: plan
  run: terraform plan -no-color

- run: echo ${{ steps.plan.outputs.stdout }}
- run: echo ${{ steps.plan.outputs.stderr }}
- run: echo ${{ steps.plan.outputs.exitcode }}

Outputs can be used in subsequent steps to comment on the pull request:

Notice: There's a limit to the number of characters inside a GitHub comment (65535).

Due to that limitation, you might end up with a failed workflow run even if the plan succeeded.

Another approach is to append your plan into the $GITHUB_STEP_SUMMARY environment variable which supports markdown.

defaults:
  run:
    working-directory: ${{ env.tf_actions_working_dir }}
permissions:
  pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3

- name: Terraform fmt
  id: fmt
  run: terraform fmt -check
  continue-on-error: true

- name: Terraform Init
  id: init
  run: terraform init

- name: Terraform Validate
  id: validate
  run: terraform validate -no-color

- name: Terraform Plan
  id: plan
  run: terraform plan -no-color
  continue-on-error: true

- uses: actions/github-script@v7
  if: github.event_name == 'pull_request'
  env:
    PLAN: "terraform\n${{ steps.plan.outputs.stdout }}"
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    script: |
      const output = `#### Terraform Format and Style šŸ–Œ\`${{ steps.fmt.outcome }}\`
      #### Terraform Initialization āš™ļø\`${{ steps.init.outcome }}\`
      #### Terraform Validation šŸ¤–\`${{ steps.validate.outcome }}\`
      <details><summary>Validation Output</summary>

      \`\`\`\n
      ${{ steps.validate.outputs.stdout }}
      \`\`\`

      </details>

      #### Terraform Plan šŸ“–\`${{ steps.plan.outcome }}\`

      <details><summary>Show Plan</summary>

      \`\`\`\n
      ${process.env.PLAN}
      \`\`\`

      </details>

      *Pusher: @${{ github.actor }}, Action: \`${{ github.event_name }}\`, Working Directory: \`${{ env.tf_actions_working_dir }}\`, Workflow: \`${{ github.workflow }}\`*`;

      github.rest.issues.createComment({
        issue_number: context.issue.number,
        owner: context.repo.owner,
        repo: context.repo.repo,
        body: output
      })

Instead of creating a new comment each time, you can also update an existing one:

defaults:
  run:
    working-directory: ${{ env.tf_actions_working_dir }}
permissions:
  pull-requests: write
steps:
- uses: actions/checkout@v4
- uses: hashicorp/setup-terraform@v3

- name: Terraform fmt
  id: fmt
  run: terraform fmt -check
  continue-on-error: true

- name: Terraform Init
  id: init
  run: terraform init

- name: Terraform Validate
  id: validate
  run: terraform validate -no-color

- name: Terraform Plan
  id: plan
  run: terraform plan -no-color
  continue-on-error: true

- uses: actions/github-script@v7
  if: github.event_name == 'pull_request'
  env:
    PLAN: "terraform\n${{ steps.plan.outputs.stdout }}"
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}
    script: |
      // 1. Retrieve existing bot comments for the PR
      const { data: comments } = await github.rest.issues.listComments({
        owner: context.repo.owner,
        repo: context.repo.repo,
        issue_number: context.issue.number,
      })
      const botComment = comments.find(comment => {
        return comment.user.type === 'Bot' && comment.body.includes('Terraform Format and Style')
      })

      // 2. Prepare format of the comment
      const output = `#### Terraform Format and Style šŸ–Œ\`${{ steps.fmt.outcome }}\`
      #### Terraform Initialization āš™ļø\`${{ steps.init.outcome }}\`
      #### Terraform Validation šŸ¤–\`${{ steps.validate.outcome }}\`
      <details><summary>Validation Output</summary>

      \`\`\`\n
      ${{ steps.validate.outputs.stdout }}
      \`\`\`

      </details>

      #### Terraform Plan šŸ“–\`${{ steps.plan.outcome }}\`

      <details><summary>Show Plan</summary>

      \`\`\`\n
      ${process.env.PLAN}
      \`\`\`

      </details>

      *Pusher: @${{ github.actor }}, Action: \`${{ github.event_name }}\`, Working Directory: \`${{ env.tf_actions_working_dir }}\`, Workflow: \`${{ github.workflow }}\`*`;

      // 3. If we have a comment, update it, otherwise create a new one
      if (botComment) {
        github.rest.issues.updateComment({
          owner: context.repo.owner,
          repo: context.repo.repo,
          comment_id: botComment.id,
          body: output
        })
      } else {
        github.rest.issues.createComment({
          issue_number: context.issue.number,
          owner: context.repo.owner,
          repo: context.repo.repo,
          body: output
        })
      }

Inputs

The action supports the following inputs:

Outputs

This action does not configure any outputs directly. However, when you set the terraform_wrapper input to true, the following outputs are available for subsequent steps that call the terraform binary:

License

Mozilla Public License v2.0

Code of Conduct

Code of Conduct

Experimental Status

By using the software in this repository (the "Software"), you acknowledge that: (1) the Software is still in development, may change, and has not been released as a commercial product by HashiCorp and is not currently supported in any way by HashiCorp; (2) the Software is provided on an "as-is" basis, and may include bugs, errors, or other issues; (3) the Software is NOT INTENDED FOR PRODUCTION USE, use of the Software may result in unexpected results, loss of data, or other unexpected results, and HashiCorp disclaims any and all liability resulting from use of the Software; and (4) HashiCorp reserves all rights to make all decisions about the features, functionality and commercial release (or non-release) of the Software, at any time and without any obligation or liability whatsoever.

Contributing

License Headers

All source code files (excluding autogenerated files like package.json, prose, and files excluded in .copywrite.hcl) must have a license header at the top.

This can be autogenerated by installing the HashiCorp copywrite tool and running copywrite headers in the root of the repository.