# Digger — Run Terraform and OpenTofu in Your Existing CI Pipeline

> Open-source IaC orchestration that runs Terraform and OpenTofu directly in your GitHub Actions, GitLab CI, or Azure DevOps pipeline. No separate CI system or state management service required.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

# Digger — Run Terraform and OpenTofu in Your Existing CI Pipeline

## Quick Use
```yaml
# .github/workflows/digger.yml
name: Digger
on: [pull_request]
jobs:
  digger:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: diggerhq/digger@v0.6
        with:
          setup-terraform: true
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
```

## Introduction
Digger runs Terraform and OpenTofu plan/apply directly inside your existing CI system rather than requiring a separate Terraform Cloud instance or custom CI server. It posts plan output as PR comments, handles locking to prevent concurrent applies, and supports multi-project monorepos out of the box.

## What Digger Does
- Executes terraform plan on pull requests and posts output as PR comments
- Runs terraform apply on merge with automatic locking to prevent conflicts
- Supports monorepos with multiple Terraform projects and dependency ordering
- Integrates natively with GitHub Actions, GitLab CI, Azure DevOps, and Bitbucket
- Provides drift detection by running scheduled plans against deployed infrastructure

## Architecture Overview
Digger operates as a CI step that detects which Terraform projects were modified in a PR, acquires a lock (stored in DynamoDB, GCS, or Postgres), runs plan/apply, and reports results. A lightweight orchestrator backend (optional, self-hosted) coordinates jobs across multiple runners and manages lock state. All Terraform execution happens in your own CI runner with your own cloud credentials, so no secrets leave your environment.

## Self-Hosting & Configuration
- Add the Digger GitHub Action or GitLab CI template to your repository
- Configure projects in a `digger.yml` file at the repo root listing directories and dependencies
- Set up a lock backend (DynamoDB table, GCS bucket, or Postgres) for state locking
- Cloud credentials stay in your CI secrets; Digger never stores or proxies them
- Enable the optional orchestrator backend via Docker for advanced features like RBAC and audit logs

## Key Features
- Runs in your CI so cloud credentials never leave your environment
- PR-level locking prevents concurrent applies to the same Terraform state
- Monorepo-aware with automatic detection of changed projects per PR
- Policy-as-code integration with OPA for plan approval gates
- Cost estimation via Infracost integration shown inline in PR comments

## Comparison with Similar Tools
- **Terraform Cloud** — hosted by HashiCorp with per-resource pricing; Digger is free and runs in your CI
- **Atlantis** — similar PR-based workflow but requires a dedicated server; Digger is serverless
- **Spacelift** — managed IaC platform; Digger keeps execution in your existing CI infrastructure
- **Env0** — SaaS with approval workflows; Digger provides similar features self-hosted
- **Terragrunt** — CLI wrapper for DRY configs; Digger is an orchestration layer, they complement each other

## FAQ
**Q: Do I need to run a separate server for Digger?**
A: No. The core functionality runs as a CI step. The optional orchestrator backend adds advanced features but is not required for basic plan/apply workflows.

**Q: How does Digger prevent two PRs from applying to the same state simultaneously?**
A: It acquires a project-level lock before running apply. Other PRs targeting the same project wait until the lock is released.

**Q: Does Digger support OpenTofu?**
A: Yes. Configure the binary path in digger.yml or use the setup-opentofu flag in the GitHub Action.

**Q: Can I use Digger with a monorepo containing 50+ Terraform projects?**
A: Yes. Digger detects which projects are affected by file changes and only runs plans for those, keeping CI times short.

## Sources
- https://github.com/diggerhq/digger
- https://docs.digger.dev

---
Source: https://tokrepo.com/en/workflows/digger-run-terraform-opentofu-your-existing-ci-pipeline-1cce94e4
Author: AI Open Source