Terraform’s stateful nature creates a unique challenge for pure GitOps, but it’s a solvable problem. This guide explores practical solutions, from simple CI/CD wrappers to dedicated tools like Atlantis, to bridge the gap and make Terraform a first-class citizen in your GitOps workflow.

Does Terraform Even *Do* GitOps? A Field Guide for the Perplexed.

I still remember the day a junior engineer, let’s call him Alex, took down half our staging environment. It was 4:45 PM on a Friday, of course. He’d been asked to add a single egress rule to a security group. He cloned the repo, made the change, and ran terraform apply from his laptop. What he didn’t know was that another engineer had manually deleted a “temporary” S3 bucket an hour earlier, a bucket that was still defined in the Terraform code. His `apply` didn’t just add the rule; it helpfully tried to “fix” the drift by deleting a bunch of other resources that depended on that S3 bucket. It was a complete mess, born from two well-intentioned people working outside of a predictable process. That’s the moment the “Terraform on your laptop” rule died forever at our company and we got serious about this exact question.

The Elephant in the Room: The Terraform State File

Before we dive into solutions, let’s get real about why this is even a discussion. The core of the GitOps philosophy is that your Git repository is the single source of truth for the desired state of your infrastructure. Tools like Argo CD or Flux are brilliant at this for Kubernetes: they see a YAML file in Git, compare it to what’s running in the cluster, and make it so.

Terraform throws a wrench in this beautiful, simple model. Why? Because it has two sources of truth:

1. Your .tf files in Git: This is your desired state. “I want three EC2 instances of this type.”
2. The terraform.tfstate file: This is Terraform’s understanding of the *current* state. “I last saw three EC2 instances with these specific IDs and IP addresses.”

Terraform uses the state file to generate a plan. It compares your code (desired state) to its state file (last known state) and the real world (actual state) to figure out what needs to be created, updated, or destroyed. A pure GitOps controller doesn’t understand this three-way reconciliation or the plan/apply lifecycle. It just wants to slap a declarative config onto an API. This mismatch is the source of all our pain.

The Fixes: From Duct Tape to Dedicated Machinery

So, how do we solve it? I’ve seen teams try everything, but the solutions generally fall into three categories. We’ll go from the quick-and-dirty to the robust and scalable.

Solution 1: The “Good Enough for Now” CI/CD Wrapper

This is the most common starting point. You treat Terraform execution as just another step in your existing CI/CD pipeline (e.g., GitHub Actions, GitLab CI, Jenkins).

The flow looks like this:

• A developer opens a Pull Request with a change to a .tf file.
• The pipeline automatically triggers, checks out the code, and runs terraform plan.
• The plan output is posted as a comment on the PR for review.
• Once the PR is approved and merged into the main branch, a separate pipeline job triggers.
• This job runs terraform apply -auto-approve.

Here’s a simplified GitHub Actions example for the `apply` step:

name: 'Terraform Apply on Main'

on:
  push:
    branches:
      - main

jobs:
  terraform:
    name: 'Terraform'
    runs-on: ubuntu-latest
    steps:
    - name: 'Checkout'
      uses: actions/checkout@v3

    - name: 'Terraform Apply'
      uses: hashicorp/terraform-github-actions@v0.1.0
      with:
        tf_actions_version: 1.2.0
        tf_actions_subcommand: 'apply'
        tf_actions_working_dir: '.'
        tf_actions_comment: false
      env:
        AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
        AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
        TF_VAR_some_variable: "value"

Darian’s Warning: This is a “push-based” approach, not a “pull-based” one like true GitOps. The pipeline pushes the change; nothing is pulling from the repo to reconcile state. If someone makes a manual change in the cloud console, this pipeline won’t know about it until the next time you run a commit. It stops the “apply from my laptop” problem, but it doesn’t fully solve for state drift.

Solution 2: The “Do It Right” GitOps Orchestrator

This is where we bring in tools designed specifically for this problem. The goal is to bring the plan/apply lifecycle directly into your Git workflow, making it transparent and collaborative.

My go-to recommendation here is Atlantis. It’s an open-source application you host yourself that listens for Terraform pull requests. It’s a game-changer.

The Atlantis flow:

1. A developer opens a Pull Request.
2. Atlantis automatically picks it up and runs terraform plan in the background.
3. It then posts the entire plan output as a clean, formatted comment right inside the PR. The whole team can see *exactly* what will change.
4. To proceed, a team member with permissions comments back: atlantis apply.
5. Atlantis runs the apply, captures the output, and posts that back to the PR as well.
6. Once merged, the change is complete and fully audited within the PR history.

This is GitOps for Terraform done right. The conversation, the plan, and the execution all live in the pull request. It becomes the unit of infrastructure change. Terraform Cloud and Spacelift offer a more polished, SaaS version of this same core workflow, with added features like policy-as-code (OPA/Sentinel) and cost estimation.

Solution 3: The “Rethink Your State” Structural Fix

Sometimes the tool isn’t the problem; the scope is. I’ve seen teams trying to manage their entire company’s infrastructure in a single, monolithic Terraform state file. A plan in that repo could take 15 minutes to run and propose changing everything from a DNS record to a production Kubernetes cluster. It’s terrifying and fragile.

The “nuclear” option here isn’t to ditch Terraform, but to radically decompose your state. Don’t have one giant state; have dozens of small ones, each with a clear, limited blast radius.

• networking-prod state: Manages the core VPC, subnets, and routing. Changes rarely.
• platform-services-prod state: Manages the EKS cluster, node groups, and core IAM roles.
• app-billing-prod state: Manages the S3 buckets, DynamoDB table, and Lambda function for just the billing application.

When you break things down this way, applying GitOps principles becomes much safer. An automated `apply` on the `app-billing-prod` state is low-risk. You can grant the pipeline credentials that *only* have access to manage those specific resources. This approach, combined with a tool like Atlantis (Solution 2), is the sweet spot for mature teams.

Final Verdict: A Side-by-Side Comparison

So, does Terraform fit into the GitOps story? Absolutely, but not out of the box. You have to be intentional. You have to bridge the gap between its stateful, imperative execution model and the declarative, self-healing world of GitOps. Start with a simple pipeline, but have a plan to graduate to a real orchestrator like Atlantis. And for the love of all that is holy, stop running terraform apply from your laptop.

Darian Vance

Lead Cloud Architect & DevOps Strategist

With over 12 years in system architecture and automation, Darian specializes in simplifying complex cloud infrastructures. An advocate for open-source solutions, he founded TechResolve to provide engineers with actionable, battle-tested troubleshooting guides and robust software alternatives.

🤖 Frequently Asked Questions