OpenTofu Support

TerraCi has first-class support for OpenTofu, the open-source Terraform fork.

Configuration

Switch to OpenTofu by setting the binary in the top-level execution: section:

execution:
  binary: tofu

extensions:
  # For GitLab CI
  gitlab:
    image: "ghcr.io/opentofu/opentofu:1.6"

  # For GitHub Actions (no provider-side binary setting; image comes from the workflow steps)
  github:
    runs_on: ubuntu-latest

How It Works

When you set execution.binary: tofu, TerraCi:

1. Stores tofu in the Terraform operation inside the pipeline IR
2. Uses tofu in all generated scripts
3. Selects the default OpenTofu image for GitLab when no custom image is configured

Generated Pipeline

default:
  image: ghcr.io/opentofu/opentofu:1.6
  before_script:
    - tofu init

plan-platform-prod-vpc:
  script:
    - cd platform/prod/us-east-1/vpc
    - tofu plan -out=plan.tfplan
  # ...

apply-platform-prod-vpc:
  script:
    - cd platform/prod/us-east-1/vpc
    - tofu apply plan.tfplan
  # ...

Official OpenTofu Images

Use official OpenTofu Docker images:

Image	Description
ghcr.io/opentofu/opentofu:latest	Latest stable
ghcr.io/opentofu/opentofu:1.6	Version 1.6.x
ghcr.io/opentofu/opentofu:1.6.0	Specific version

Mixed Environments

If you have both Terraform and OpenTofu modules, you can override per-job:

# In your custom pipeline template
.tofu-job:
  image: ghcr.io/opentofu/opentofu:1.6

.terraform-job:
  image: hashicorp/terraform:1.6

Then extend the generated jobs as needed.

State Compatibility

OpenTofu is compatible with Terraform state files. You can:

1. Keep existing Terraform state files
2. Migrate to OpenTofu without state changes
3. Use the same S3/GCS backends

TerraCi's dependency resolution works identically for both.

Migration Guide

From Terraform to OpenTofu

1. Update .terraci.yaml:

   execution:
     binary: tofu
   
   extensions:
     # GitLab CI
     gitlab:
       image: "ghcr.io/opentofu/opentofu:1.6"
   
     # GitHub Actions
     github:
       runs_on: ubuntu-latest

2. Regenerate pipelines:

   terraci generate -o .gitlab-ci.yml

3. Test with dry-run:

   terraci generate --dry-run

4. Commit and push

Gradual Migration

Migrate module by module using job overrides:

# Override specific jobs to use OpenTofu
apply-platform-prod-vpc:
  extends: .tofu-job

Version Compatibility

TerraCi works with:

Tool	Supported Versions
Terraform	0.12+
OpenTofu	1.0+

The HCL parsing is compatible with both.

Binary Selection

execution.binary accepts the canonical runtime values terraform and tofu. TerraCi writes that binary onto Terraform jobs in the IR, and providers/local execution render commands directly from the operation:

execution:
  binary: tofu

Environment Variables

Add OpenTofu-specific environment variables through execution.env. They are applied to Terraform plan/apply jobs only, not to provider workflow globals or standalone plugin command jobs:

execution:
  binary: tofu
  env:
    TF_CLI_CONFIG_FILE: "/etc/tofu/config.tfrc"
    TOFU_LOG: "INFO"

extensions:
  # GitLab
  gitlab:
    variables:
      TF_CLI_CONFIG_FILE: "/etc/tofu/config.tfrc"

  # GitHub Actions
  github:
    env:
      TF_CLI_CONFIG_FILE: "/etc/tofu/config.tfrc"

Next Steps

• Getting Started — Install TerraCi and set up your first project
• GitLab CI Configuration — Full reference for GitLab pipeline configuration options