Statamic Git Sync Laravel Package

Product Decisions This Supports

• Build vs. buy for content versioning. Statamic ships Pro automation for git, but this package covers the gaps teams actually hit: pull-request workflows instead of direct pushes to a base branch, per-event-type toggles, a scheduled safety net for missed events, and a control-panel audit widget. The build-vs-buy question narrows to "do we need PR review on content, or is an append-only commit log enough?" — this package answers the first, cheaply.
• Editorial governance and compliance roadmap. Every content type in the release (entries, terms, taxonomies, globals, navs, assets, collections, blueprints, fieldsets, forms, users, roles, sites) is individually switchable, so you can scope a rollout to just the collections under audit rather than committing the whole site on day one. That maps directly to a phased governance rollout: start with regulated content, expand later.
• Feature scoping on "who changed what." The control panel user is credited as commit author with a configurable fallback, plus a "Recent content syncs" widget with per-file status and +/− counts. That is a shippable answer to the most common stakeholder ask in CMS work ("who edited this and when") without building a custom audit log.
• Release-engineering decisions for the deploy pipeline. statamic:git-sync:doctor exits non-zero, so it can be a deploy gate. Thirteen health checks with remediation text turn "git sync is flaky in staging" from an open-ended support burden into a checklist.
• Risk posture on automation. Commit-only-to-configured-paths, refusal to commit during a half-finished merge/rebase/cherry-pick, pull --rebase with abort-and-restore, and SyncManager::sync() never throwing into a control panel save — these are explicit product decisions about not breaking the editor's session. Adoption here is low-blast-radius, which shortens the internal approval conversation.
• Notification and on-call design. Failures and conflicts notify inline rather than queued, on the stated grounds that a queue-dependent failure alert is useless when the queue is the failure. That is a defensible operational stance worth adopting as a precedent for other internal tooling.
• Integration surface for platform work. Sixteen contracts, six typed events, and a PullRequestClientContract with GitHub and GitLab implementations mean this can be wired into existing Slack/ops/pipeline tooling rather than becoming a bespoke silo.
• Roadmap signal on Statamic Solo. Explicit Solo support plus PHP 8.2–8.4 and Statamic 5/6 means this is viable for the small-site tier, not just enterprise installs — relevant if the product roadmap includes a low-touch tier with versioned content.

When to Consider This Package

Adopt when most of these hold:

• You run Statamic 5 or 6 and content lives in flat files you want versioned, but you do not want editors thinking about git.
• You need review before publish on content — strategy => 'pull-request' is the differentiating capability and the reason to pick this over Pro automation.
• Multiple editors write concurrently, so per-save commits would flood history. Trailing-edge debouncing is the specific fix.
• You want a deploy gate and health checks rather than discovering sync breakage from editors.
• You need audit attribution per control panel user, or a widget showing what each sync touched.
• You want to phase coverage by content type rather than all-or-nothing.
• You are on a cache store that supports atomic locks, or you accept immediate-commit mode with the doctor warning.

Look elsewhere, or wait, when:

• v0.1.0 is the whole story. This is a first release. There is no migration history, no deprecation policy, and no evidence yet of how the sixteen contracts behave across a major Statamic upgrade. Treat the extension points as a one-way door until a 1.0 or a clear stability statement exists.
• You are on Statamic 4 or earlier, or PHP below 8.2 — unsupported.
• You need sync to a non-git VCS, or a forge other than GitHub/GitLab. The contract makes it extensible, but you would be writing it.
• Your team expects queued notifications for throughput; inline sending is a deliberate design choice, not a config.
• You need sub-second or event-stream-level fidelity — the debounce window plus scheduled safety net means commits are eventually consistent by design. If "commit happened before the API responded" is a requirement, this is the wrong architecture.
• Your repository is shared with application code and you cannot cleanly isolate content paths. git commit --only protects hand-staged files, but a messy repo still produces noisy history.
• You want a managed/SaaS audit trail. This is a self-hosted package; operating git credentials, remotes and forge tokens stays your job.

How to Pitch It (Stakeholders)

To executives: Content changes are currently untracked or tracked by convention. This package makes every content edit a git commit — attributable to the person who made it, reviewable before it reaches the live site, and reversible with standard git tooling. The pull-request mode is the commercially interesting part: it puts editorial changes through the same review gate as code, which is usually a compliance or brand-safety requirement we would otherwise have to build. It is a small, self-hosted package with no vendor lock-in, and it fails safe — it refuses to commit over an in-progress merge rather than risk corrupting the repo.

To engineering: It is a Statamic addon, PHP 8.2–8.4, Statamic 5 and 6, including Solo. It hooks Statamic content events and commits only configured paths using git commit --only, so it never picks up or unstages work someone did by hand. Debounces per editing session, with a scheduled sweep for anything the event path missed (flushed cache, dead queue worker) so the worst case is a delay, not a lost commit. It never checks out a branch — the PR strategy pushes the current branch and opens/reuses a PR — which avoids swapping files under an editor mid-save. Sixteen contracts and six typed events mean we can swap commit-message formatting, path filtering, forge clients and health checks from our own service provider without forking. doctor exits non-zero and is usable as a CI/deploy gate. SyncManager::sync() does not throw into the save request by design.

The honest caveat to state up front: this is v0.1.0. Functionally it is a considered release — failure classification with backoff, URL credential redaction, conflict handling that defers to a human, a JSONL history file that survives cache:clear — but there is no track record. Propose it as a bounded pilot on one or two collections, behind the doctor gate, with the extension contracts treated as unstable until a 1.0 lands. If the pilot's only output is a clean decision on PR-gated content versus commit-log-only, it has paid for itself.