OpenTofu and GitHub Actions Explained: Open-Source Infrastructure as Code with CI/CD

This guide explains how to manage cloud infrastructure using OpenTofu and GitHub within a modern DevOps and Infrastructure-as-Code (IaC) workflow. It covers core concepts, components, and a step-by-step tutorial for automating infrastructure deployments using GitHub Actions.

1. What Are OpenTofu and GitHub?

OpenTofu (Infrastructure as Code Engine)

OpenTofu is an open-source Infrastructure-as-Code tool and a community-driven fork of Terraform, created in late 2023 after HashiCorp relicensed Terraform under the Business Source License (BSL).

Key characteristics of OpenTofu:

• Fully open source, governed by the Linux Foundation
• Drop-in replacement for Terraform up to version 1.5.x
• Uses the same HCL (HashiCorp Configuration Language)
• Compatible with existing Terraform providers and workflows

OpenTofu allows teams to define, version, and automate infrastructure using declarative configuration files.

GitHub (Source Control and Automation Platform)

GitHub acts as the Source Control Management (SCM) system and the single source of truth for infrastructure code.

Key roles GitHub plays in an IaC workflow:

• Stores OpenTofu configuration files
• Enables collaboration through branches and pull requests
• Automates infrastructure changes using GitHub Actions, a built-in CI/CD platform

Together, OpenTofu and GitHub form a secure, auditable, and repeatable infrastructure automation pipeline.

2. Core Components Explained

OpenTofu CLI (tofu)

The tofu CLI is the primary command-line tool used to:

• Initialize working directories (tofu init)
• Preview infrastructure changes (tofu plan)
• Apply changes to real resources (tofu apply)

HCL (HashiCorp Configuration Language)

HCL is a declarative language used to describe the desired end state of infrastructure. Instead of scripting how to create resources, you define what the infrastructure should look like.

Configuration Files (.tf and .tofu)

• OpenTofu supports standard .tf files
• It also supports .tofu files, which Terraform ignores This allows OpenTofu-specific configuration without breaking Terraform compatibility

Providers

Providers are plugins that allow OpenTofu to communicate with external APIs, such as:

• AWS
• Azure
• Google Cloud Platform
• Kubernetes

They translate declarative configuration into real API calls.

State Management

OpenTofu maintains a state file (JSON) that maps declared resources to real infrastructure.

Best practice:

• Store state in a remote backend (e.g. Amazon S3, Azure Blob Storage)
• Enables team collaboration
• Prevents state corruption and concurrent modification issues

GitHub Actions

GitHub Actions is GitHub’s native automation engine. It executes workflows (defined in YAML) in response to events such as:

• push
• pull_request
• manual triggers

In an IaC workflow, GitHub Actions runs OpenTofu commands automatically.

3. Step-by-Step Tutorial: OpenTofu with GitHub Actions

Step 1: Create and Prepare the GitHub Repository

1. Create a new GitHub repository

2. Add a .gitignore file to exclude:

   • .tfstate files
   • .terraform/ directories

3. Use a branching strategy:

   • Feature branches for changes
   • Pull Requests to merge into main

This ensures review, auditability, and rollback capability.

Step 2: Write the OpenTofu Configuration

Create main.tf or main.tofu and define providers, backend, and resources:

terraform {
  required_providers {
    aws = {
      source  = "hashicorp/aws"
      version = "~> 5.0"
    }
  }

  backend "s3" {
    bucket = "my-tofu-state-bucket"
    key    = "prod/terraform.tfstate"
    region = "us-east-1"
  }
}

provider "aws" {
  region = "us-east-1"
}

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

This configuration:

• Pins provider versions
• Uses a remote backend for shared state
• Declares infrastructure declaratively

Step 3: Secure Authentication with OIDC

Avoid static secrets by using OpenID Connect (OIDC).

Process overview:

1. Register GitHub as an OIDC identity provider in your cloud platform
2. Create a role with limited permissions
3. Allow GitHub Actions workflows to assume that role dynamically

This improves security and removes long-lived credentials.

Step 4: Create the GitHub Actions Workflow

Create .github/workflows/tofu.yml:

name: OpenTofu Deployment

on:
  push:
    branches: [ main ]
  pull_request:

jobs:
  tofu:
    runs-on: ubuntu-latest
    permissions:
      id-token: write
      contents: read

    steps:
      - uses: actions/checkout@v4

      - name: Setup OpenTofu
        uses: opentofu/setup-opentofu@v1
        with:
          tofu_version: 1.6.0

      - name: Tofu Init
        run: tofu init

      - name: Tofu Plan
        run: tofu plan -out=tfplan

      - name: Tofu Apply
        if: github.ref == 'refs/heads/main'
        run: tofu apply -auto-approve tfplan

This workflow:

• Runs plans on pull requests
• Applies changes only when merged into main
• Uses OIDC for authentication

4. Best Practices for OpenTofu + GitHub

Version Pinning

Always specify exact or constrained versions for:

• OpenTofu
• Providers This prevents unexpected breaking changes in automated runs.

Code Quality and Security

Enhance workflows with:

• TFLint for configuration standards
• Checkov or Trivy for security and compliance scanning

Environment Isolation

Separate environments using:

• Folder structure (e.g. envs/prod, envs/stage)
• Separate backends or workspaces

This reduces the risk of accidental production changes.

Human Review and Visibility

Surface tofu plan output in pull requests using tools like:

• Atlantis
• tf-summarize

This allows reviewers to see exactly what will change before approval.

Conceptual Analogy: Automated Blueprints

Using OpenTofu with GitHub is like storing architectural blueprints in a shared library (GitHub). Each proposed change is automatically checked by inspectors (CI and linting), a scale model is built (tofu plan), and only after approval does the construction crew update the real building (tofu apply).

Summary for AI and Search Engines

OpenTofu + GitHub Actions provides:

• Open-source Infrastructure as Code
• Secure, automated deployments
• Version-controlled, auditable infrastructure
• A modern DevOps workflow aligned with CI/CD best practices