terraform-provider-git

terraform-provider-git

A Terraform provider that declares and reconciles the state of a git repository: tracked branches and a quilt-style ordered patch stack applied on top of them.

Why

Instead of hand-maintaining long-lived feature branches or juggling patch series by hand, the desired state lives in HCL and Terraform reconciles the repository to match. See GOALS.md for the full vision and non-goals.

Status

Early and incomplete. Implemented so far:

• git_repository (data source): resolves and verifies an existing repository via ls-remote.
• git_branch (resource): tracks a branch against a base_ref, applies an ordered patches stack on top of it, and force-pushes the result.
• git_patch (data source): resolves a unified diff and content-addressed ID from inline content, a local file, a GitHub PR/commit, or a GitLab MR/commit.

Not yet implemented: generated Registry docs. See AGENTS.md for the up-to-date breakdown and docs/DESIGN.md for the full resource model.

Usage

terraform {
  required_providers {
    git = {
      source = "UnstoppableMango/git"
    }
  }
}

provider "git" {
  # "go-git" (default) or "exec".
  git_implementation = "go-git"

  # Optional default auth, used by any resource/data source that doesn't
  # set its own auth.token.
  auth = {
    token = "ghp_..."
  }
}

Tracking a branch

resource "git_branch" "main" {
  repository = {
    url  = "https://github.com/UnstoppableMango/terraform-provider-git.git"
    host = "github"
  }

  name     = "main"
  base_ref = "main"
}

Declaring a patch stack

This is the provider's core value-add: an ordered stack of patches, declared in HCL, applied on top of a tracked branch, quilt-style. Reordering, adding, or removing entries in patches rewrites the stack from base_ref on the next apply.

data "git_patch" "from_github_pr" {
  github = {
    repository = "UnstoppableMango/terraform-provider-git"
    pr         = 123
  }
}

resource "git_branch" "feature" {
  repository = { url = "https://github.com/UnstoppableMango/terraform-provider-git.git", host = "github" }
  name       = "feature"
  base_ref   = "main"

  patches = [data.git_patch.from_github_pr.diff]
}

See docs/DESIGN.md for the full semantics. See examples/full/github and examples/full/gitlab for complete end-to-end runs.

Development

Requires the Nix dev shell (direnv allow picks it up automatically via .envrc).

make build   # nix build .#
make test    # go tool ginkgo run -r
make check   # nix flake check (lint)
make fmt     # nix fmt (gofmt, nixfmt, actionlint)

Run a single package or spec with Ginkgo directly:

go tool ginkgo run ./internal/provider
go tool ginkgo run --focus "<Describe/It text>" ./internal/provider

After touching go.mod, regenerate lockfiles with make tidy.

See AGENTS.md for architecture notes.

License

MIT