GitHub Actions Configuration

The github section configures the generated GitHub Actions workflow. This section is used when the resolved provider is github (auto-detected from the GITHUB_ACTIONS environment variable, or set via the TERRACI_PROVIDER environment variable). When the provider is gitlab, this section is omitted and the gitlab section is used instead. See GitLab CI Configuration for the GitLab equivalent.

Options

terraform_binary

Type: stringDefault: "terraform"

The Terraform/OpenTofu binary to use.

plugins:
  github:
    terraform_binary: "terraform"  # or "tofu"

runs_on

Type: stringDefault: "ubuntu-latest"

The GitHub Actions runner label for jobs.

plugins:
  github:
    runs_on: "ubuntu-latest"
    # runs_on: "self-hosted"

container

Type: object (optional) Default: none

Optionally run jobs inside a container. Supports both string and object format.

plugins:
  github:
    container:
      name: "hashicorp/terraform:1.6"
      entrypoint: [""]

env

Type: map[string]stringDefault: {}

Workflow-level environment variables.

plugins:
  github:
    env:
      TF_IN_AUTOMATION: "true"
      TF_INPUT: "false"
      AWS_DEFAULT_REGION: "us-east-1"

plan_enabled

Type: booleanDefault: true

Generate separate plan jobs.

plugins:
  github:
    plan_enabled: true   # plan + apply jobs
    # plan_enabled: false  # apply only

plan_only

Type: booleanDefault: false

Generate only plan jobs without apply jobs.

plugins:
  github:
    plan_only: true

auto_approve

Type: booleanDefault: false

Auto-approve apply jobs without environment protection.

plugins:
  github:
    auto_approve: false  # Apply uses environment protection
    # auto_approve: true   # Apply runs automatically

init_enabled

Type: booleanDefault: true

Automatically run terraform init before terraform commands.

plugins:
  github:
    init_enabled: true

permissions

Type: map[string]stringDefault: {}

Workflow-level permissions. Required for PR comments and OIDC authentication.

plugins:
  github:
    permissions:
      contents: read
      pull-requests: write
      id-token: write        # Required for OIDC

job_defaults

Type: objectDefault: null

Default settings applied to all generated jobs (both plan and apply). These are applied before overwrites.

Available fields:

• runs_on - Override runner label for all jobs
• container - Container image for all jobs
• env - Additional environment variables
• steps_before - Extra steps to run before terraform commands
• steps_after - Extra steps to run after terraform commands

Example: Common setup steps for all jobs

plugins:
  github:
    job_defaults:
      steps_before:
        - uses: actions/checkout@v4
        - uses: hashicorp/setup-terraform@v3
        - name: Configure AWS credentials
          uses: aws-actions/configure-aws-credentials@v4
          with:
            role-to-assume: arn:aws:iam::123456789012:role/terraform
            aws-region: us-east-1
      steps_after:
        - name: Upload logs
          run: echo "Job completed"

Each step in steps_before / steps_after supports:

• name - Step display name
• uses - GitHub Action reference (e.g., actions/checkout@v4)
• with - Action inputs as key-value pairs
• run - Shell command to run
• env - Step-level environment variables

overwrites

Type: arrayDefault: []

Job-level overrides for plan or apply jobs. Applied after job_defaults.

Each overwrite has:

• type - Which jobs to override: plan or apply
• runs_on - Override runner label
• container - Override container image
• env - Override/add environment variables
• steps_before - Override steps before terraform commands
• steps_after - Override steps after terraform commands

Example: Different runners for plan and apply

plugins:
  github:
    overwrites:
      - type: plan
        runs_on: ubuntu-latest

      - type: apply
        runs_on: self-hosted
        env:
          DEPLOY_ENV: "production"

Example: Extra steps for apply jobs

plugins:
  github:
    overwrites:
      - type: apply
        steps_before:
          - uses: actions/checkout@v4
          - uses: hashicorp/setup-terraform@v3
          - name: Approve deployment
            run: echo "Deploying..."

pr

Type: objectDefault: null

Pull request integration settings. Equivalent to GitLab's mr section.

plugins:
  github:
    pr:
      comment:
        enabled: true
        on_changes_only: false

pr.comment

Controls PR comment behavior:

Field	Type	Default	Description
enabled	bool	true	Enable PR comments
on_changes_only	bool	false	Only comment when there are changes
include_details	bool	true	Include full plan output in expandable sections

Full Example

plugins:
  github:
    # Binary configuration
    terraform_binary: "terraform"
    runs_on: "ubuntu-latest"

    # Workflow settings
    plan_enabled: true
    auto_approve: false
    init_enabled: true

    # Workflow-level environment variables
    env:
      TF_IN_AUTOMATION: "true"
      TF_INPUT: "false"

    # Permissions (required for PR comments and OIDC)
    permissions:
      contents: read
      pull-requests: write
      id-token: write

    # Job defaults (applied to all jobs)
    job_defaults:
      steps_before:
        - uses: actions/checkout@v4
        - uses: hashicorp/setup-terraform@v3
        - name: Configure AWS credentials
          uses: aws-actions/configure-aws-credentials@v4
          with:
            role-to-assume: arn:aws:iam::123456789012:role/terraform
            aws-region: us-east-1

    # Job overwrites (override job_defaults for specific job types)
    overwrites:
      - type: apply
        runs_on: self-hosted

    # Pull request integration
    pr:
      comment:
        enabled: true
        on_changes_only: false

Per-Job Environment Variables

Like GitLab, each job receives environment variables dynamically generated from your structure.pattern segments. For the default pattern {service}/{environment}/{region}/{module}:

Variable	Description	Example
TF_MODULE_PATH	Relative path to module	platform/prod/us-east-1/vpc
TF_SERVICE	Service name	platform
TF_ENVIRONMENT	Environment name	prod
TF_REGION	Region name	us-east-1
TF_MODULE	Module name	vpc

Variable names are derived by uppercasing the segment name and prefixing with TF_.

Comparison with GitLab Configuration

Feature	GitLab (gitlab:)	GitHub (github:)
Runner selection	job_defaults.tags	runs_on
Container image	image	container (optional)
Pre-job commands	job_defaults.before_script	job_defaults.steps_before
Post-job commands	job_defaults.after_script	job_defaults.steps_after
Pipeline variables	variables	env
Access control	rules	permissions
MR/PR integration	mr section	pr section
Secrets	secrets (Vault)	Use GitHub Action steps
OIDC tokens	id_tokens	permissions.id-token: write
Caching	cache_enabled	Use actions/cache in steps
Stages prefix	stages_prefix	N/A (uses job dependencies)

See Also

• GitLab CI Configuration — the equivalent configuration for GitLab CI
• Merge Request Integration — MR comments with plan summaries and policy results
• Pipeline Generation Guide — end-to-end guide for generating CI pipelines