MetaStackr (git-meta)

MetaStackr is an event-driven meta-repository orchestration system built in Go 1.25 with a PostgreSQL backend and a custom CLI (git-meta).

It enables developers to work transparently across a root meta-repository containing multiple Git submodules. Developers operate locally using familiar Git workflows, while MetaStackr automatically creates, tracks, synchronizes, and atomically merges child pull requests across sub-repositories on GitHub.

---

Key Features

• Standardized Local Workflow (git-meta):

  • git meta status: Interrogates local submodule drift (uncommitted changes, unpushed commits) merged with live remote PR/CI status via terminal tables.
  • git meta checkout [-b] <branch>: Safely creates or switches branches across parent meta-repo and all submodules.
  • git meta commit -m "<msg>": Creates coordinated atomic commits across all modified submodules and updates parent commit pointers.
  • git meta push: Enforces bottom-up pushing (pushes submodule origins before parent commit pointers).
  • git meta create-pr: Opens or creates GitHub Pull Requests across all modified submodules and meta-repo.
  • git meta sync: Fetches origin/main, fast-forwards/rebases local submodules, and aligns root pointers.
  • git meta rebase <upstream>: Conducts a two-phase rebase: rebases child submodules first, then parent meta-repo references.
  • git meta retry-merge --pr <pr-number>: Re-triggers cascade merges on partially failed PRs.
  • git meta install-hooks: Installs post-checkout and pre-commit hooks into .git/hooks.
  • git meta init: Onboards repository with backend registration, Git hooks installation, and GitHub webhooks setup.
  • git meta setup-webhook: Automates repository webhook registration with GitHub.
  • git meta agents: Displays guidelines and machine-readable instructions for AI agents.
  • git meta version: Displays semantic version information.

• Event-Driven Orchestration Daemon (metastackrd):

  • Webhook Ingestion: HMAC-SHA256 signature verification (X-Hub-Signature-256) processing pull_request, pull_request_review, check_run, and workflow_run events.
  • Single GitHub Check Run (meta-repo/sync): Posts and continuously updates a markdown matrix table on the Meta PR without creating comment noise.
  • Topological DAG Engine & Cycle Detection: Analyzes submodule dependencies into a Directed Acyclic Graph (DAG) and aborts if circular dependencies ($A \rightarrow B \rightarrow A$) are detected.
  • Saga Cascade Merge & Optimistic Locking: Uses SQL lock_version to prevent worker race conditions. Merges child PRs topologically in parallel batches, updates submodule pointers, and handles partial failures gracefully with retry resumption.

---

Privacy-by-Default (Opt-In Code Access)

By default, the MetaStackr server is data-blind. It does not pull, clone, or cache your repository source code, orchestrating merges exclusively via branch metadata, commit SHAs, and GitHub APIs.

Opting In to Code Access

To enable server-side code access, toggle allow_code_pull to true in your repository setup.

What you get if you opt in:

1. Static Dependency Analysis: Allows the server to inspect source files to automatically build and sort topological dependency DAGs based on code imports.
2. Local Merge Dry-Runs: Executes dry-run merges on the server to catch file conflicts early and flag FAILED_DRIFT before pushing updates to GitHub.
3. Advanced Line-Level Diff Warnings: Generates detailed warnings inside GitHub Check Runs highlighting exact code-level alignment mismatches.

---

Quick Start

1. Install CLI (git-meta)

One-Line Installation Script (macOS / Linux):

curl -fsSL https://raw.githubusercontent.com/eliotstocker/MetaStackR/main/install.sh | bash

Or Build & Install from Source:

make build
make install # Installs git-meta to /usr/local/bin/git-meta
make build-extensions # (Optional) Package Chrome, VS Code, & JetBrains extensions

Now git meta works natively in your terminal!

Shell Autocompletion:

Enable tab-completion for git meta and git-meta by adding one of the following to your shell profile:

# Zsh (~/.zshrc)
source <(git meta completion zsh)

# Bash (~/.bashrc)
source <(git meta completion bash)

2. Connect Your VCS Provider (GitHub / GitLab)

MetaStackr natively supports both GitHub and GitLab:

• GitHub App: Install the official MetaStackr GitHub App for zero-config repository webhook & status check orchestration.
• GitLab Integration: Connect your organization via MetaStackr GitLab OAuth or supply a Group Access Token (git meta config vcs-token glpat-xxxx).

3. Run Backend Daemon (metastackrd)

Set your database and credentials:

export DATABASE_URL="postgres://postgres:postgres@localhost:5432/metastackr?sslmode=disable"
export WEBHOOK_SECRET="your-webhook-secret"
export GH_TOKEN="ghp_your_github_token"
export GITLAB_CLIENT_ID="your_gitlab_client_id"
export GITLAB_CLIENT_SECRET="your_gitlab_client_secret"

./metastackrd

The daemon will automatically execute embedded database migrations on startup and start listening on port :8080.

---

Architecture Overview

┌─────────────────────────────────────────────────────────────────────────┐
│                           LOCAL WORKSPACE                               │
│  - git-meta CLI (Thin client querying backend / local Git state)        │
│  - Git Hooks (post-checkout, pre-commit) for local submodule drift      │
└────────────────────────────────────┬────────────────────────────────────┘
                                     │ HTTP Status Query / Git Push
                                     v
┌─────────────────────────────────────────────────────────────────────────┐
│                       ORCHESTRATION BACKEND (GO)                        │
│                                                                         │
│  ┌───────────────────────┐             ┌─────────────────────────────┐  │
│  │ Webhook Ingestion     ├────────────>│ State & Reconciliation      │  │
│  │ Normalize GitHub Data │             │ DAG Engine (PostgreSQL)     │  │
│  └───────────────────────┘             └──────────────┬──────────────┘  │
│                                                       │                 │
│                                                       v                 │
│                                        ┌─────────────────────────────┐  │
│                                        │ Execution Engine            │  │
│                                        │ Cascade Merges / Check Runs │  │
│                                        └─────────────────────────────┘  │
└─────────────────────────────────────────────────────────────────────────┘

---

Multi-Component Semantic Release

MetaStackr uses independent per-component Semantic Release workflows based on conventional commit scopes:

Component	Scope Format	Tag Format	Artifacts
Core (git-meta & metastackrd)	feat(core): ..., fix(cli): ..., fix(daemon): ... (or unscoped)	v1.x.x	git-meta, metastackrd
VS Code Extension	feat(vscode): ..., fix(vscode): ...	vscode-v1.x.x	metastackr-vscode.vsix
Chrome Extension	feat(chrome): ..., fix(chrome): ...	chrome-v1.x.x	metastackr-chrome.zip
JetBrains Plugin	feat(jetbrains): ..., fix(jetbrains): ...	jetbrains-v1.x.x	metastackr-jetbrains.zip

To trigger a release for a specific component, prefix your commit message with the corresponding scope.

---

Documentation & Guides

• 📖 Detailed User Guide: Comprehensive operational guide, CLI reference, and troubleshooting.
• 🤖 Agent Instructions (AGENTS.md): Workspace rules and context for AI coding agents.

---

License

MIT