Statamic Git Sync Laravel Package

Technical Evaluation

Architecture fit
This is a Statamic-focused Laravel package that adds Git-backed version control for content changes. The architecture aligns well with Statamic’s event-driven content model: it subscribes to content events, debounces bursts of editorial saves, and commits only configured paths. The use of 16 contracts for commit messages, path filtering, sync strategies, forge clients, and health checks gives the package a clean extension seam without requiring forks. The package also separates control-plane concerns — doctor commands, health checks, notifications, events, and a control panel widget — from the sync path. That separation is important for a CMS addon because editorial saves must not fail because Git or a remote forge is unavailable. The release explicitly states SyncManager::sync() never throws and the subscriber only queues, which is the right failure posture for a TPM evaluating editorial safety.

Integration feasibility
Feasible for teams already on Statamic 5 or 6 with PHP 8.2–8.4. The package assumes a working Git repository, Git binary, Git identity, configured remote, and a cache store capable of atomic locks for debouncing. It works on Statamic Solo, which broadens suitability for smaller sites. Pull-request mode is a meaningful differentiator versus direct-push automation: it supports GitHub and GitLab, reuses open pull requests, and avoids checking out another branch underneath an editor. Notifications, a control panel widget, JSONL sync history, and six typed events provide operational visibility. Key integration caveats: Laravel version compatibility is not stated in the release notes, multi-node deployment behavior is not addressed, and teams must validate their Git hosting authentication model, cache driver, queue worker, and filesystem layout before enabling automatic pushes.

Technical risk
The main risk is not Statamic integration; it is Git workflow collision. Automated commits can interfere with manual staging, merges, rebases, or cherry-picks if not carefully bounded. The release mitigates this well: git commit --only restricts commits to configured paths, manual staged files stay out, and the package refuses to commit during half-finished merge/rebase/cherry-pick states. Pull mode aborts on conflict and restores the working tree. Debouncing reduces commit noise but depends on atomic cache locks; without them, the package falls back to immediate commits and surfaces a doctor warning. Other risks include multi-server races on the same working tree, forge API rate limits or token scope issues, large binary assets, and operational blind spots if notifications or the widget are not monitored. Credential redaction in logs is a positive control. Since this is v0.1.0, pre-1.0 API churn and limited production history should be treated as adoption risks.

Key questions

• Which Laravel versions are supported alongside Statamic 5/6?
• What is the recommended deployment topology for multi-node or load-balanced Statamic installations?
• Does the package require a dedicated Git working copy, or can it safely operate on the application’s existing content directory?
• How are large assets, binary files, and Git LFS handled?
• What cache drivers are known to provide the atomic locks required for debouncing?
• What queue connection and worker model are expected, and which node should run the scheduled safety net?
• What GitHub/GitLab token scopes and branch protection settings are required for pull-request mode?
• Are there dry-run, observe-only, or staging modes to validate behavior before enabling production commits?
• What is the support model for v0.1.x, and how frequently are contracts expected to change before 1.0?

Integration Approach

Stack fit
This fits a Laravel + Statamic stack where content is file-based and already intended to live in Git. It is especially relevant for teams that want an audit trail, rollback capability, and an editorial review workflow without asking editors to use Git directly. The package should be treated as infrastructure around Statamic, not as a generic Laravel Git library. The natural integration is Composer installation, configuration publishing, environment-specific Git settings, and enabling sync per content type. Pull-request mode fits teams with GitHub or GitLab branch protection and review requirements. Direct-push mode fits Solo or low-risk sites where the repository is dedicated to content.

Migration path
Adopt incrementally. Start in a staging or non-production environment with a dedicated Git repository and a clean working tree. Configure Git identity and remote access first, then run statamic:git-sync:doctor as a gate. Enable one low-risk content type before turning on the full event surface. Validate commit messages, author attribution, notifications, widget history, and scheduled safety-net behavior. If the team needs editorial review, enable pull-request mode against a protected base branch rather than pushing directly. After staging proves stable, promote configuration to production with the doctor command wired into deploy checks. Teams should document that manual Git operations on the content repository remain possible but must respect the package’s working-tree assumptions.

Compatibility
Stated compatibility is PHP 8.2, 8.3, and 8.4; Statamic 5 and 6; and Statamic Solo. Pull-request mode requires GitHub or GitLab and appropriate API credentials. Debouncing requires a cache store with atomic locks. The scheduled safety net requires a scheduler and likely a queue worker for queued sync paths, though the release notes say notifications are sent inline. Laravel framework constraints, Git version requirements, and hosting-specific limitations are not specified and should be verified during a spike. Windows support, containerized ephemeral filesystems, and multi-node shared-storage behavior also need validation.

Sequencing

1. Provision a dedicated content repository or confirm the existing repository is safe for automated commits.
2. Configure deploy keys or forge tokens with least-privilege access.
3. Install the package and publish configuration in staging.
4. Set Git identity, fallback author, content paths, cache store, queue, and notification channels.
5. Run statamic:git-sync:doctor and resolve all non-zero findings before enabling writes.
6. Enable one content type with direct commits or pull-request mode depending on review requirements.
7. Validate debounce behavior, commit authorship, path filtering, conflict handling, and notification delivery.
8. Add the scheduled safety net and confirm it runs on exactly one appropriate node.
9. Add the doctor command to CI/CD as a deploy gate.
10. Roll out to production, then expand content-type coverage and monitor failures through events, notifications, and the control panel widget.

Operational Impact

Maintenance
Operational maintenance is moderate. The package reduces manual content-versioning effort, but it introduces a Git-backed automation layer that must be kept healthy. Teams should pin the package version during v0.1.x, watch release notes for contract changes, and periodically re-run doctor checks after Statamic, PHP, Laravel, Git, or hosting changes. The JSONL history file under storage/ survives cache clears, which is useful, but retention and rotation should be considered. Repository growth, commit volume, and pull-request volume should be monitored. The 16 contracts are valuable for customization, but custom implementations become maintenance surface area.

Support
Support requires a blend of Statamic/Laravel application ownership and Git operational competence. The doctor command, health checks, typed events, notifications, and widget give support teams actionable signals, but someone must own conflict resolution, forge token rotation, and Git remote failures. Because v0.1.0 is an early release, teams should expect community-style support unless they have a commercial arrangement. Runbooks should cover: doctor failures, authentication failures, network retry exhaustion, merge conflicts, cache lock unavailability, queue worker outages, and pull-request API errors. Inline failure notifications are good, but they must route to a monitored channel.

Scaling
Scaling is the most important operational constraint. Git is not a distributed concurrent-write system, and automated content sync assumes a coherent working tree. Single-node or single-writer deployments are the safest fit. Multi-node deployments need a clear leader for sync operations, a shared cache with atomic locks, and a strategy for ensuring only one Git process mutates the content working tree at a time. Large repositories, large asset files, and high editorial concurrency will increase commit and push latency. Pull-request mode reduces direct-push risk but can increase review overhead and forge API usage. The scheduled safety net improves resilience after cache flushes or queue outages, but it also means delayed commits rather than immediate consistency.

Failure modes
Expected failure modes include missing Git binary, dirty repository, missing Git identity, bad remote credentials, network failure on push, merge/rebase/cherry-pick in progress, merge conflicts during pull/rebase, unsupported cache lock driver, stopped queue worker, cleared cache, forge API failure, and notification delivery failure. The package classifies failures sensibly: network push failures retry with backoff; missing Git binary and conflicts do not retry. Conflicts require human intervention. Because sync failures do not throw into control panel saves, editors may continue working while commits are delayed or failing; monitoring must therefore rely on notifications, events, the widget, and doctor checks rather than editor-facing errors. Credential redaction reduces log-leak risk, but token handling and repository permissions still require security review.

Ramp-up
Ramp-up is moderate for a Laravel/Statamic team and higher for teams without Git fluency. The doctor command and health checks substantially lower setup risk. The control panel widget and translations improve editor-facing visibility. Console output remaining English is reasonable for deploy logs. Training should cover the difference between direct-push and pull-request modes, how debouncing affects commit timing, what the safety net does, how to interpret sync history, and how to resolve conflicts without corrupting the automated workflow. A staged rollout with one content type and a protected base branch is the recommended ramp.