GitHub Actions - Reusable Terraform Workflows

Reusable GitHub Workflows to run state-of-the-art Terraform pipelines. Static code checks such as format, documentation, lint, and security best practices are performed within Github Actions, and Terraform Plan and Apply are forwarded to Terraform Enterprise or Cloud via API. These workflows can also be used to test Terraform modules with Terratest and can automatically release new module versions.

Terraform Workflow

Quick Start

To get started add github-terraform-workflows to an existing GitHub workflow:

• Terraform VCS Workflow
• Terraform Workspace Workflow
• Terraform Module Workflow
• Terraform Module Workflow (Matrix)
  
  

Configuration Repositories (optional)

• github-tflint-config
• github-terratest-config
• github-terraform-semantic-release-config
  
  

Referenced Github Actions

The reusable Github Workflows include the following public Github Actions:

• @actions/checkout
• @actions/setup-go
• @ad-m/github-push-action
• @cycjimmy/semantic-release-action
• @hashicorp/setup-terraform
• @octokit/request-action
• @reviewdog/action-tflint
• @reviewdog/action-trivy
• @terraform-docs/gh-actions
• @terraform-linters/tflint-load-config-action

In addition to these Github Actions, custom bash scripts are run to avoid using unverified actions.

Terraform VCS Workflow

• This workflow can be used to run Terraform code in a VCS driven workflow

❗ Requirements

• Can be used with any VCS compatible Terraform pipeline

Workflow Steps

The Terraform VCS workflow consists of the following steps:

On Pull Request Event

1. Terraform Format
2. Terraform Docs
3. Terraform Lint
4. Terraform Security
5. Publish Result

On Push Event

1. Terraform Format
2. Terraform Docs
3. Terraform Lint
4. Terraform Security
   
   

Inputs [Terraform VCS Workflow]

Name	Description	Default	Required
github_runner	Name of GitHub-hosted runner or self-hosted runner	ubuntu-latest	false
terraform_version	Terraform version used inside github action	latest	false
terraform_working_directory	A relative path starting with '.' that Terraform will execute within (e.g. './infrastructure')	.	false
tflint_repo	Public repo where tflint config is stored. Format: owner/name	nuvibit/github-tflint-config	false
tflint_repo_config_path	Path to tflint config in tflint_repo (e.g. "aws/.tflint.hcl")	""	false
tflint_repo_ref	Ref or branch of tflint_repo	main	false
tflint_version	Tflint version to use in github action	lastest	false
trivy_version	Trivy version to use in github action	lastest	false
commit_user	Username which should be used for commits by github action	github-actions	false
commit_email	Email which should be used for commits by github action	noreply@github.com	false

Secrets [Terraform VCS Workflow]

Name	Description	Default	Required
GHE_API_TOKEN	Github (Enterprise) API Token is required to pull private terraform module dependencies directly from github	""	true

Usage [Terraform VCS Workflow]

name: TERRAFORM VCS

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  terraform-vcs:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-vcs.yml@v1
    with:
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}

Terraform Workspace Workflow

• This workflow can be used to run Terraform code in a CLI driven workflow

❗ Requirements

• A Terraform Enterprise or Cloud workspace is required.
• The Terraform workspace should be configured for CLI runs.
• The terraform repository should contain a remote backend.

Workflow Steps

The Terraform workspace workflow consists of the following steps:

On Pull Request Event

1. Terraform Format
2. Terraform Docs
3. Terraform Lint
4. Terraform Security
5. Terraform Plan
6. Publish Result

On Push Event

1. Terraform Format
2. Terraform Docs
3. Terraform Lint
4. Terraform Security
5. Terraform Apply
   
   

Inputs [Terraform Workspace Workflow]

Name	Description	Default	Required
github_runner	Name of GitHub-hosted runner or self-hosted runner	ubuntu-latest	false
tfe_hostname	Terraform Enterprise/Cloud hostname	app.terraform.io	false
terraform_version	Terraform version used inside github action	latest	false
terraform_working_directory	A relative path starting with '.' that Terraform will execute within (e.g. './infrastructure')	.	false
tflint_repo	Public repo where tflint config is stored. Format: owner/name	nuvibit/github-tflint-config	false
tflint_repo_config_path	Path to tflint config in tflint_repo (e.g. "aws/.tflint.hcl")	""	false
tflint_repo_ref	Ref or branch of tflint_repo	main	false
tflint_version	Tflint version to use in github action	lastest	false
trivy_version	Trivy version to use in github action	lastest	false
commit_user	Username which should be used for commits by github action	github-actions	false
commit_email	Email which should be used for commits by github action	noreply@github.com	false

Secrets [Terraform Workspace Workflow]

Name	Description	Default	Required
GHE_API_TOKEN	Github (Enterprise) API Token is required to pull private terraform module dependencies directly from github	""	true
TFE_API_TOKEN	Terraform Enterprise/Cloud API Token is required to authenticate with Terraform workspace	""	true

Usage [Terraform Workspace Workflow]

name: TERRAFORM WORKSPACE

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  terraform-workspace:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-workspace.yml@v1
    with:
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}
      TFE_API_TOKEN: ${{ secrets.TFE_API_TOKEN }}

Usage [Terraform Workspace Workflow + custom working directory]

name: TERRAFORM WORKSPACE PRODUCTION
on:
  pull_request:
    branches:
      - main
    paths:
      - 'production/**'
  push:
    branches:
      - main
    paths:
      - 'production/**'
jobs:
  terraform-workspace:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-workspace.yml@v1
    with:
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
      terraform_working_directory: "./production"
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}
      TFE_API_TOKEN: ${{ secrets.TFE_API_TOKEN }}

Terraform Module Workflow

• This workflow can be used to run Terratest for a Terraform module.
• This workflow releases the module automatically with semantic versioning.
• This workflow can only test a single Terraform version.

❗ Requirements

• An AWS account is required to run Terratest.

Workflow Steps

The Terraform module workflow consists of the following steps:

On Pull Request Event

1. Terraform Format
2. Terraform Docs
3. Terraform Lint
4. Terraform Security
5. Terraform Terratest
6. Publish Result

On Push Event

1. Disable Branch Protection
2. Release module
3. Enable Branch Protection
   
   

Inputs [Terraform Module Workflow]

Name	Description	Default	Required
github_runner	Name of GitHub-hosted runner or self-hosted runner	ubuntu-latest	false
tfe_hostname	Terraform Enterprise/Cloud hostname	app.terraform.io	false
use_opentofu	Use OpenTofu instead of Terraform	false	false
terraform_version	Terraform version used to format code	latest	false
registry_hostname	Hostname for terraform registry used to download providers	registry.terraform.io	false
terratest_version	Terratest version	v0.46.12	false
terratest_path	Path to terratest directory	test	false
terratest_examples_path	Path to terratest example directory	examples	false
tflint_repo	Public repo where tflint config is stored. Format: owner/name	nuvibit/github-tflint-config	false
tflint_repo_config_path	Path to tflint config in tflint_repo (e.g. "aws/.tflint.hcl")	""	false
tflint_repo_ref	Ref or branch of tflint_repo	main	false
tflint_version	Tflint version to use in github action	lastest	false
trivy_version	Trivy version to use in github action	lastest	false
commit_user	Username which should be used for commits by github action	github-actions	false
commit_email	Email which should be used for commits by github action	noreply@github.com	false

Secrets [Terraform Module Workflow]

Name	Description	Default	Required
GHE_API_TOKEN	Github (Enterprise) API Token is required to pull private terraform module dependencies directly from github	""	true
TFE_API_TOKEN	Terraform Enterprise/Cloud API Token is required to authenticate with Terraform workspace	""	true
TERRATEST_AWS_DEFAULT_REGION	AWS Default Region for Terratest Account	""	false
TERRATEST_AWS_ACCESS_KEY_ID	AWS Access Key for Terratest Account	""	false
TERRATEST_AWS_SECRET_ACCESS_KEY	AWS Secret Access Key for Terratest Account	""	false

Inputs [Terraform Release Workflow]

Name	Description	Default	Required
github_runner	Name of GitHub-hosted runner or self-hosted runner	ubuntu-latest	false
toggle_branch_protection	Temporary disable branch protection to allow release action to push updates to changelog	true	false
semantic_version	Specify specifying version range for semantic-release	18.0.0	false
semantic_release_config	Shareable config to create release of Terraform Modules	@nuvibit/github-terraform-semantic-release-config	false
release_branch	Name of branch on which Terraform Module release should happen	main	false

Secrets [Terraform Release Workflow]

Name	Description	Default	Required
GHE_API_TOKEN	Github (Enterprise) API Token is required to pull private terraform module dependencies directly from github	""	true

Usage [Terraform Module Matrix + Release Workflow]

name: TERRAFORM MODULE

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  terraform-module:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module.yml@v1
    if: ${{ github.event_name == 'pull_request' }}
    with:
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}
      TFE_API_TOKEN: ${{ secrets.TFE_API_TOKEN }}
      TERRATEST_AWS_DEFAULT_REGION: ${{ secrets.TERRATEST_AWS_DEFAULT_REGION }}
      TERRATEST_AWS_ACCESS_KEY_ID: ${{ secrets.TERRATEST_AWS_ACCESS_KEY_ID }}
      TERRATEST_AWS_SECRET_ACCESS_KEY: ${{ secrets.TERRATEST_AWS_SECRET_ACCESS_KEY }}

  terraform-module-release:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-release.yml@v1
    if: ${{ github.event_name == 'push' }}
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}

Terraform Module Workflow (Matrix)

• This workflow can be used to run Terratest for a Terraform module.
• This workflow releases the module automatically with semantic versioning.
• This workflow uses a matrix strategy to allow testing of different Terraform versions.

❗ Requirements

• An AWS account or Azure subscription is required to run Terratest.
• For this workflow a Terraform Enterprise or Cloud workspace is required.
• The Terraform workspace should be configured for local runs.
• The terraform repository should contain a remote backend.

Workflow Steps

The Terraform module workflow consists of the following steps:

On Pull Request Event

1. Terraform Format
2. Terraform Docs
3. Terraform Lint
4. Terraform Security
5. Terraform Terratest (multiple versions via matrix)
6. Publish Result

On Push Event

1. Disable Branch Protection
2. Release module
3. Enable Branch Protection
   
   

Inputs [Terraform Module Matrix Workflow]

Name	Description	Default	Required
github_runner	Name of GitHub-hosted runner or self-hosted runner	ubuntu-latest	false
tfe_hostname	Terraform Enterprise/Cloud hostname	app.terraform.io	false
terraform_version	Terraform version used to format code	latest	false
registry_hostname	Hostname for terraform registry used to download providers	registry.terraform.io	false
terratest_version	Terratest version	v0.46.12	false
terratest_path	Path to terratest directory	test	false
terratest_examples_path	Path to terratest example directory	examples	false
terratest_max_parallel	Maximum number of terratest runs that should run simultaneously	1	false
terratest_config_repo	Public repo where terratest matrix json is stored	nuvibit/github-terratest-config	false
terratest_config_repo_ref	Ref or branch of terratest_config_repo	main	false
terratest_config_repo_path	Path to terratest matrix json config in terratest_config_repo (e.g. "aws/matrix.json")	""	false
tflint_repo	Public repo where tflint config is stored. Format: owner/name	nuvibit/github-tflint-config	false
tflint_repo_config_path	Path to tflint config in tflint_repo (e.g. "aws/.tflint.hcl")	""	false
tflint_repo_ref	Ref or branch of tflint_repo	main	false
tflint_version	Tflint version to use in github action	lastest	false
trivy_version	Trivy version to use in github action	lastest	false
commit_user	Username which should be used for commits by github action	github-actions	false
commit_email	Email which should be used for commits by github action	noreply@github.com	false

Secrets [Terraform Module Matrix Workflow]

Name	Description	Default	Required
GHE_API_TOKEN	Github (Enterprise) API Token is required to pull private terraform module dependencies directly from github	""	true
TFE_API_TOKEN	Terraform Enterprise/Cloud API Token is required to authenticate with Terraform workspace	""	true
TERRATEST_AWS_DEFAULT_REGION	AWS Default Region for Terratest Account	""	false
TERRATEST_AWS_ACCESS_KEY_ID	AWS Access Key for Terratest Account	""	false
TERRATEST_AWS_SECRET_ACCESS_KEY	AWS Secret Access Key for Terratest Account	""	false

Inputs [Terraform Release Workflow]

Name	Description	Default	Required
github_runner	Name of GitHub-hosted runner or self-hosted runner	ubuntu-latest	false
toggle_branch_protection	Temporary disable branch protection to allow release action to push updates to changelog	true	false
semantic_version	Specify specifying version range for semantic-release	18.0.0	false
semantic_release_config	Shareable config to create release of Terraform Modules	@nuvibit/github-terraform-semantic-release-config	false
release_branch	Name of branch on which Terraform Module release should happen	main	false

Secrets [Terraform Release Workflow]

Name	Description	Default	Required
GHE_API_TOKEN	Github (Enterprise) API Token is required to pull private terraform module dependencies directly from github	""	true

Usage [Terraform Module Matrix + Release Workflow]

name: TERRAFORM MODULE

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main

jobs:
  terraform-module:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-matrix.yml@v1
    if: ${{ github.event_name == 'pull_request' }}
    with:
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
      terratest_config_repo: "nuvibit/github-terratest-config"
      terratest_config_repo_path: "aws/matrix.json"
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}
      TFE_API_TOKEN: ${{ secrets.TFE_API_TOKEN }}
      TERRATEST_AWS_DEFAULT_REGION: ${{ secrets.TERRATEST_AWS_DEFAULT_REGION }}
      TERRATEST_AWS_ACCESS_KEY_ID: ${{ secrets.TERRATEST_AWS_ACCESS_KEY_ID }}
      TERRATEST_AWS_SECRET_ACCESS_KEY: ${{ secrets.TERRATEST_AWS_SECRET_ACCESS_KEY }}

  terraform-module-release:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-release.yml@v1
    if: ${{ github.event_name == 'push' }}
    secrets:
      GHE_API_TOKEN: ${{ secrets.GHE_API_TOKEN }}

Authors

This collection is maintained by Nuvibit with help from these amazing contributors

License

This collection is licensed under Apache 2.0
See LICENSE for full details

Copyright © 2023 Nuvibit AG