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

Execution settings

binary, init_enabled, parallelism, and Terraform job env live under the top-level execution: section, not under extensions.github. Plan jobs are derived from apply intent and resource requests such as plan.json consumers.

runs_on

Type: stringDefault: "ubuntu-latest"

The GitHub Actions runner label for jobs.

extensions:
  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.

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

env

Type: map[string]stringDefault: {}

Workflow-level environment variables.

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

Use terraci generate --plan-only for read-only workflows. There is no provider-level plan toggle.

permissions

Type: map[string]stringDefault: {}

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

extensions:
  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
• if - Job condition
• environment - GitHub Actions environment
• 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

extensions:
  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, apply, or an exact contributed job name
• runs_on - Override runner label
• container - Override container image
• env - Override/add environment variables
• if - Job condition
• environment - GitHub Actions environment
• steps_before - Override steps before terraform commands
• steps_after - Override steps after terraform commands

Example: Different runners for plan and apply

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

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

Example: Extra steps for apply jobs

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

Full Example

execution:
  binary: terraform
  init_enabled: true

extensions:
  github:
    runs_on: "ubuntu-latest"

    # 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

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
• Summary Configuration — MR/PR comments with plan summaries and plugin reports
• Pipeline Generation Guide — end-to-end guide for generating CI pipelines