GitHub Actions - Reusable Terraform / OpenTofu Workflows

Reusable GitHub Workflows to run state-of-the-art Terraform and OpenTofu pipelines with flexible deployment strategies. Built by Nuvibit, the leading specialist in sovereign AWS platforms and creator of the Nuvibit Terraform Collection (NTC).

This collection provides workflows for two distinct Infrastructure as Code scenarios:

For deploying and managing infrastructure on AWS using Terraform/OpenTofu:

• Primary Workflow: terraform-stack.yml
• Purpose: Deploy infrastructure changes to cloud environments
• Target: Infrastructure repositories, environment-specific deployments
• Features: Quality gates, optional plan/apply execution, multi-environment support

For developing, testing, and releasing reusable Terraform modules:

• Workflows: terraform-module-test.yml + terraform-module-release.yml
• Purpose: Automated testing with Terratest and semantic versioning releases
• Target: Terraform module repositories, library development
• Features: OIDC authentication, matrix testing with dynamic provider versions, automated releases

The infrastructure deployment workflows support two distinct deployment patterns:

Perfect for teams using dedicated IaC management platforms while maintaining quality gates in GitHub:

• GitHub Actions Role: Performs all static code quality checks (format, docs, lint, security)
• External Platform Role: Handles terraform plan/apply execution
• Supported Platforms: Terraform Cloud, Spacelift, Atlantis, and other IaC platforms
• Benefits: Leverage specialized IaC tooling while maintaining code quality standards
• Configuration: Set enable_terraform_execution: false (default)

Ideal for teams wanting a complete Infrastructure as Code pipeline within GitHub Actions:

• GitHub Actions Role: Handles everything - quality checks AND terraform execution
• Deployment Flow: Plan on PR → Apply on merge to main branch
• Features: Plan/apply summaries in workflow results, automated execution, full workflow visibility
• Benefits: Single platform for all IaC operations, simplified toolchain
• Configuration: Set enable_terraform_execution: true

Both approaches support Terraform and OpenTofu, provide comprehensive quality gates, and integrate seamlessly with cloud providers for infrastructure deployment.

Choose the appropriate workflow category for your use case:

• Terraform Stack Workflow - Deploy infrastructure with quality gates and optional execution
• Workflow Trigger - Trigger dependent workflows for stack orchestration

• Terraform Module Test Workflow - Automated testing with Terratest
• Terraform Module Release Workflow - Automated semantic versioning and releases
  
  

All workflows use GitHub Apps instead of the default GITHUB_TOKEN for enhanced security:

• Scoped Permissions: Apps can be granted specific, minimal permissions
• No User Association: Not tied to individual user accounts
• Audit Trail: All actions are logged and attributed to the app
• Token Refresh: Short-lived tokens that refresh automatically
• Repository-Specific: Access can be limited to specific repositories

1. Create a GitHub App in your organization settings
2. Grant Permissions: contents: write, pull-requests: write, issues: write, checks: write
3. Install App: Install on repositories / organization where workflows will run
4. Set Secrets: Store App ID and private key as repository / organization secrets

For accessing private Terraform modules hosted on Github, create a separate GitHub App with:

• Permissions: contents: read, metadata: read
• Repository Access: Only the module repositories needed
• Principle of Least Privilege: Minimal access for maximum security

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

The reusable Github Workflows include the following public Github Actions:

• @actions/checkout
• @actions/setup-go
• @actions/create-github-app-token
• @ad-m/github-push-action
• @aws-actions/configure-aws-credentials
• @cycjimmy/semantic-release-action
• @hashicorp/setup-terraform
• @opentofu/setup-opentofu
• @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 Stack Workflow

• Purpose: Deploy and manage infrastructure on AWS using Terraform/OpenTofu
• Target: Infrastructure repositories, environment-specific deployments, cloud resource management
• This workflow provides a complete Terraform/OpenTofu CI/CD pipeline with quality gates
• Supports both Terraform and OpenTofu
• Flexible deployment modes: Static checks only OR complete CI/CD with execution
• Optional terraform plan on pull requests and apply on push to default branch

Static Checks Mode (enable_terraform_execution: false)

• Use when leveraging external IaC platforms (Terraform Cloud, Spacelift, etc.)
• GitHub Actions handles quality assurance (format, docs, lint, security)
• External platform handles terraform plan/apply execution
• Ideal for enterprise environments with dedicated IaC tooling

Complete CI/CD Mode (enable_terraform_execution: true)

• Use for full GitHub Actions-based Infrastructure as Code pipeline
• All operations (quality checks + terraform execution) in GitHub Actions
• Plan results posted as PR comments, apply on merge to main
• Perfect for teams wanting unified workflow platform

• Terraform/OpenTofu Support: Seamless switching between tools
• Quality Gates: Format, documentation, lint, and security checks
• OPA Policy Validation: Enforce custom policies on Terraform plans with Open Policy Agent
• Optional Execution: Enable terraform plan/apply with simple toggle
• GitHub App Authentication: Enhanced security with scoped tokens instead of GITHUB_TOKEN
• Private Module Support: Access private Terraform modules via GitHub App authentication
• Private Registry Support: Support for private Terraform module registries
• AWS OIDC Integration: Secure, keyless authentication with AWS using OpenID Connect
• Workflow Summaries: Plan and apply results displayed in GitHub workflow summaries
• Branch Protection: Apply only runs on specified default branch
• Flexible Configuration: Extensive customization options

The Terraform Stack workflow consists of the following steps:

Optional Quality Gates (enabled by default)

1. Terraform Format - Code formatting with auto-commit (can be disabled with enable_terraform_fmt: false)
2. Terraform Docs - Documentation generation (can be disabled with enable_terraform_docs: false)
3. Terraform Lint - Static code analysis with TFLint (can be disabled with enable_terraform_lint: false)
4. Terraform Security - Security scanning with Trivy (can be disabled with enable_terraform_security: false)

Optional Execution (disabled by default) 5. Terraform Plan - On pull requests and manual triggers on non-default branches (results in workflow summary) 6. OPA Policy Check - Validate Terraform plan against custom policies (can be enabled with enable_opa_policy_check: true) 7. Terraform Apply - On push to default branch or manual trigger on default branch (auto-approve) 8. Workflow Summary - Centralized status reporting with skip indicators

Perfect for teams using Terraform Cloud, Spacelift, or other IaC platforms

name: TERRAFORM STACK

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

jobs:
  terraform-stack:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-stack.yml@v2
    with:
      enable_terraform_execution: false # (default) Run static checks only
      # Optional: disable specific quality gates
      # enable_terraform_fmt: false
      # enable_terraform_docs: false
      # enable_terraform_lint: false
      # enable_terraform_security: false
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

Full GitHub Actions pipeline with terraform plan/apply

name: TERRAFORM STACK

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main
  workflow_dispatch:  # Enable manual triggers

jobs:
  terraform-stack:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-stack.yml@v2
    with:
      enable_terraform_execution: true  # Enable complete CI/CD mode
      aws_oidc_role_arn: ${{ secrets.AWS_OIDC_ROLE_ARN }}
      default_branch: "main"
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

Execution Behavior:

• Pull Requests: Runs terraform plan (results in workflow summary)
• Push to main: Runs terraform apply with auto-approve
• Manual Trigger on main: Runs terraform apply with auto-approve
• Manual Trigger on other branches: Runs terraform plan for testing

OpenTofu with full CI/CD pipeline

name: OPENTOFU STACK

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

jobs:
  opentofu-stack:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-stack.yml@v2
    with:
      use_opentofu: true
      enable_terraform_execution: true
      aws_oidc_role_arn: ${{ secrets.AWS_OIDC_ROLE_ARN }}
      terraform_version: "1.8.0"
      terraform_working_directory: "./infrastructure"
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

Using private Terraform modules and private registry

name: TERRAFORM STACK

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  terraform-stack:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-stack.yml@v2
    with:
      enable_terraform_execution: true
      terraform_modules_auth: "github-app"
      terraform_modules_github_owner: "your-org"
      terraform_registry_hostname: "registry.example.com"
      aws_oidc_role_arn: ${{ secrets.AWS_OIDC_ROLE_ARN }}
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}
      TERRAFORM_MODULES_APP_ID: ${{ secrets.TERRAFORM_MODULES_APP_ID }}
      TERRAFORM_MODULES_APP_PRIVATE_KEY: ${{ secrets.TERRAFORM_MODULES_APP_PRIVATE_KEY }}
      TERRAFORM_REGISTRY_TOKEN: ${{ secrets.TERRAFORM_REGISTRY_TOKEN }}

Enforce custom policies on Terraform plans

name: TERRAFORM STACK WITH OPA

on:
  pull_request:
    branches: [main]
  push:
    branches: [main]

jobs:
  terraform-stack:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-stack.yml@v2
    with:
      enable_terraform_execution: true
      aws_oidc_role_arn: ${{ secrets.AWS_OIDC_ROLE_ARN }}
      
      # Enable OPA policy validation
      enable_opa_policy_check: true
      opa_policy_repo: "nuvibit/terraform-opa-policies"
      opa_policy_repo_ref: "main"
      
      # Select specific policies using patterns
      # Supports wildcards: aws/*.rego, aws/**/*.rego
      # Mix files and patterns: ["common.rego", "aws/*.rego", "security/encryption.rego"]
      opa_policy_repo_paths: '["aws/*.rego", "global/common.rego"]'
      
      # Optional: Fail on warnings (default is only denials)
      opa_fail_on_warn: false
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

OPA Policy Path Patterns:

• "aws/*.rego" - All .rego files in aws directory
• "aws/**/*.rego" - All .rego files in aws and subdirectories
• "global/common.rego" - Specific file
• '["common/*.rego", "aws/tagging.rego"]' - Multiple patterns

OPA Results:

• Denials: Block terraform apply (workflow fails)
• Warnings: Informational only (unless opa_fail_on_warn: true)
• Results are displayed in the workflow summary

Workflow Trigger

• Purpose: Trigger dependent workflows in other repositories for stack orchestration
• Target: Infrastructure repositories with dependencies, multi-stack deployments
• This workflow enables automated triggering of workflows in other repositories within the same organization
• Perfect for implementing stack dependencies and sequential deployments
• Supports waiting for completion and failure propagation

• Organization-Scoped: Triggers workflows within the same GitHub organization
• Sequential Orchestration: Chain multiple terraform stacks with dependencies
• Optional Monitoring: Wait for triggered workflows to complete
• Failure Propagation: Optionally fail if dependent workflows fail
• Custom Inputs: Pass configuration to triggered workflows
• Flexible Triggers: Support for PR, push, or both events
• GitHub App Authentication: Secure, scoped authentication
• Comprehensive Reporting: Detailed status summaries in workflow results

Single Job - Parallel or Sequential Execution

1. Parse Configuration - Load workflow trigger definitions
2. Trigger Workflows - Dispatch workflows to target repositories
3. Monitor Completion - (Optional) Wait for triggered workflows to finish
4. Summary Report - Display trigger status and results

[
  {
    "repo": "repository-name",
    "workflow": "terraform.yml",
    "ref": "main",
    "inputs": {
      "custom_param": "value"
    }
  }
]

Note: repo is the repository name within your organization. The organization is automatically detected from the calling workflow.

name: Terraform Stack with Dependencies

on:
  pull_request:
    branches:
      - main
  push:
    branches:
      - main
  # required if this workflow needs to be triggered by a dependency
  workflow_dispatch:

jobs:
  terraform-stack:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-stack.yml@v2
    with:
      enable_terraform_execution: true
      aws_oidc_role_arn: ${{ secrets.AWS_ROLE_ARN }}
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

  # Trigger dependent workflows after successful terraform apply
  trigger-dependencies:
    needs: terraform-stack
    if: success()
    uses: nuvibit/github-terraform-workflows/.github/workflows/github-workflow-trigger.yml@v2
    with:
      trigger_on_event: push
      wait_for_completion: true
      fail_on_error: true
      trigger_workflows: |
        [
          {
            "repo": "dependent-stack-repo",
            "workflow": "terraform-stack.yml",
            "ref": "main"
          }
        ]
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

Terraform Module Test Workflow

• Purpose: Automated testing and validation of reusable Terraform modules
• Target: Terraform module repositories, library development, module marketplaces
• This workflow runs comprehensive testing for Terraform modules using Terratest
• Includes format, documentation, lint, security, and integration testing
• Supports both Terraform and OpenTofu with OIDC authentication for secure cloud testing

• OIDC Authentication: Secure, keyless authentication with AWS using OpenID Connect
• GitHub App Authentication: Enhanced security with scoped tokens instead of GITHUB_TOKEN
• Private Module Support: Access private Terraform modules via GitHub App authentication
• Private Registry Support: Support for private Terraform module registries
• Matrix Testing: Support for testing multiple Terraform/OpenTofu versions and provider combinations
• Dynamic Provider Versions: Automatic resolution of provider versions from requirements or latest versions
• Quality Gates: Format, docs, lint, and security checks before integration testing
• Terratest Integration: Comprehensive integration testing with Go-based Terratest framework
• Workflow Summaries: Detailed test results displayed in GitHub workflow summaries
• Parallel Testing: Configurable parallel test execution with terratest_max_parallel
• Automated Formatting: Auto-commits formatting and documentation changes
• Comprehensive Reporting: Detailed test summaries and workflow status in GitHub Actions

Sequential Pipeline - Each step depends on previous success

1. Terraform Format - Code formatting with auto-commit to PR branch
2. Terraform Docs - Documentation generation for modules and submodules
3. Terraform Lint - Static code analysis with configurable TFLint rules
4. Terraform Security - Security scanning with Trivy on examples directory
5. Terratest Config - Dynamic matrix generation from configuration repository
6. Terratest Run - Integration testing with real infrastructure using OIDC
7. Workflow Summary - Centralized status reporting with visual indicators

Note: This workflow uses OIDC authentication with AWS, eliminating the need for long-lived AWS credentials. Configure your AWS OIDC provider and specify the role ARN in aws_oidc_role_arn.

name: TERRAFORM MODULE TEST

on:
  pull_request:
    branches:
      - main

jobs:
  terraform-module-test:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-test.yml@v2
    with:
      # Required: AWS OIDC role for secure authentication
      aws_oidc_role_arn: ${{ vars.AWS_OIDC_ROLE_ARN }}
      
      # Optional: Customize linting configuration
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
      
      # Optional: Customize testing configuration
      terratest_version: "v0.48.0"
      terratest_max_parallel: 2
      terratest_timeout_in_minutes: 60
      
      # Optional: Use OpenTofu instead of Terraform
      # use_opentofu: true
      # terraform_version: "1.8.0"
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}
      # Optional: For Spacelift integration
      SPACELIFT_API_KEY_ENDPOINT: ${{ secrets.SPACELIFT_API_KEY_ENDPOINT }}
      SPACELIFT_API_KEY_ID: ${{ secrets.SPACELIFT_API_KEY_ID }}
      SPACELIFT_API_KEY_SECRET: ${{ secrets.SPACELIFT_API_KEY_SECRET }}

name: OPENTOFU MODULE TEST

on:
  pull_request:
    branches:
      - main

jobs:
  opentofu-module-test:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-test.yml@v2
    with:
      use_opentofu: true
      terraform_version: "1.8.0"
      aws_oidc_role_arn: ${{ vars.AWS_OIDC_ROLE_ARN }}
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

Terraform Module Release Workflow

• Purpose: Automated versioning and releasing of Terraform modules
• Target: Terraform module repositories, library maintenance, version management
• This workflow automatically releases Terraform modules with semantic versioning
• Integrates with conventional commit standards
• Manages branch protection and changelog generation

• Semantic Versioning: Automated version bumping based on commit messages
• Changelog Generation: Automatic changelog updates
• Branch Protection: Temporary bypass for release commits
• GitHub Releases: Automated release creation with tags
• Conventional Commits: Follows conventional commit standards

On Push to Main Branch

1. Checkout - Repository checkout
2. Branch Protection Toggle - Temporarily disable if enabled
3. Semantic Release - Analyze commits and create release
4. Branch Protection Restore - Re-enable branch protection

name: TERRAFORM MODULE RELEASE

on:
  push:
    branches:
      - main

jobs:
  terraform-module-release:
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-release.yml@v2
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}

name: TERRAFORM MODULE

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

jobs:
  terraform-module-test:
    if: ${{ github.event_name == 'pull_request' }}
    uses: nuvibit/github-terraform-workflows/.github/workflows/terraform-module-test.yml@v2
    with:
      aws_oidc_role_arn: ${{ vars.AWS_OIDC_ROLE_ARN }}
      tflint_repo: "nuvibit/github-tflint-config"
      tflint_repo_config_path: "aws/.tflint.hcl"
    secrets:
      GH_APP_ID: ${{ secrets.GH_APP_ID }}
      GH_APP_PRIVATE_KEY: ${{ secrets.GH_APP_PRIVATE_KEY }}
      # spacelift credentials used to test spacelift administration
      SPACELIFT_API_KEY_ENDPOINT: ${{ secrets.SPACELIFT_API_KEY_ENDPOINT }}
      SPACELIFT_API_KEY_ID: ${{ secrets.SPACELIFT_API_KEY_ID }}
      SPACELIFT_API_KEY_SECRET: ${{ secrets.SPACELIFT_API_KEY_SECRET }}

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

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

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

Copyright © Nuvibit AG