OpenTofu Support

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

Configuration

Switch to OpenTofu by updating .terraci.yaml:

plugins:
  # For GitLab CI
  gitlab:
    terraform_binary: "tofu"
    image: "ghcr.io/opentofu/opentofu:1.6"

  # For GitHub Actions
  github:
    terraform_binary: "tofu"

How It Works

When you set terraform_binary: "tofu", TerraCi:

1. Sets TERRAFORM_BINARY=tofu in the pipeline variables
2. Uses ${TERRAFORM_BINARY} in all generated scripts
3. Generates commands like tofu init, tofu plan, tofu apply

Generated Pipeline

variables:
  TERRAFORM_BINARY: "tofu"

default:
  image: ghcr.io/opentofu/opentofu:1.6
  before_script:
    - ${TERRAFORM_BINARY} init

plan-platform-prod-vpc:
  script:
    - cd platform/prod/us-east-1/vpc
    - ${TERRAFORM_BINARY} plan -out=plan.tfplan
  # ...

apply-platform-prod-vpc:
  script:
    - cd platform/prod/us-east-1/vpc
    - ${TERRAFORM_BINARY} 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:
  variables:
    TERRAFORM_BINARY: "tofu"
  image: ghcr.io/opentofu/opentofu:1.6

.terraform-job:
  variables:
    TERRAFORM_BINARY: "terraform"
  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 (for your provider):

   plugins:
     # GitLab CI
     gitlab:
       terraform_binary: "tofu"
       image: "ghcr.io/opentofu/opentofu:1.6"
   
     # GitHub Actions
     github:
       terraform_binary: "tofu"

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.

Custom Binary Path

If your binary has a custom name or path:

plugins:
  # GitLab
  gitlab:
    terraform_binary: "/usr/local/bin/tofu-1.6"
    before_script:
      - ${TERRAFORM_BINARY} init

  # GitHub Actions
  github:
    terraform_binary: "/usr/local/bin/tofu-1.6"

Environment Variables

Set OpenTofu-specific environment variables:

plugins:
  # GitLab
  gitlab:
    variables:
      TERRAFORM_BINARY: "tofu"
      TF_CLI_CONFIG_FILE: "/etc/tofu/config.tfrc"
      TOFU_LOG: "INFO"

  # GitHub Actions
  github:
    variables:
      TERRAFORM_BINARY: "tofu"
      TF_CLI_CONFIG_FILE: "/etc/tofu/config.tfrc"
      TOFU_LOG: "INFO"

Next Steps

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