Statamic Git Sync Laravel Package

Getting Started

Install the addon with Composer, publish its config, and run php artisan statamic:git-sync:doctor before enabling anything. The doctor is the first place to look: it checks the git binary, repository state, identity, branch, remote, content paths, pull-request setup, notifications, history file, cache lock support, queue driver and safety net, and exits non-zero on problems.

A sensible first configuration is narrow: point the package at the Statamic content paths you actually want versioned, enable syncing for entries only, and configure the commit author fallback for console/scheduled runs. Then edit an entry in the control panel and confirm that one debounced commit appears rather than one commit per save.

Add statamic:git-sync to the scheduler early. The event path handles normal editing, but the scheduled run is the safety net for flushed caches, stopped queue workers and missed events.

First real use case: automatic Git history for editorial content changes on Statamic Solo, with the control panel user credited as commit author and a “Recent content syncs” widget for visibility.

Implementation Patterns

• Enable event groups incrementally. Entries, terms, taxonomies, globals, navs, assets, collections, blueprints, fieldsets, forms, users, roles and sites are individually switchable; start with the content types that change day to day and leave structural/config events off until the workflow is trusted.
• Use trailing-edge debouncing for editorial sessions. Tune the debounce window so a burst of saves becomes one commit, but verify your cache store supports atomic locks; otherwise the package falls back to immediate commits and doctor warns you.
• Treat the scheduled statamic:git-sync command as part of the deployment/operations contract. It closes the gap when an event is missed, so a cleared cache or stopped worker costs a delay rather than a lost commit.
• Use commit message templates with {summary}, {count}, {user}, {date} and {files}. Keep the Committed-by: statamic-git-sync trailer intact: it is the loop guard.
• For review workflows, set strategy => 'pull-request'. The package pushes the current branch and opens or reuses a pull request against the configured base branch, which is useful when content changes need editorial or client approval before landing on the main branch.
• In pull-request mode, do not expect the package to check out another branch. It deliberately avoids swapping content files underneath an editor. Configure GitHub or GitLab credentials and rely on doctor to reject a head/base branch setup that cannot work.
• Enable notifications selectively. Failures, conflicts and opened pull requests are the high-value notifications; successful commits can get noisy. Notifications are sent inline rather than queued, so they still work when the queue is the broken component.
• Use the control panel widget and JSONL history file for day-to-day auditability. The history survives cache:clear, which makes it more useful than cache-backed status during deploys.
• Listen for SyncStarted, SyncCompleted, SyncSkipped, SyncFailed, ConflictDetected and PullRequestOpened when integrating with external monitoring or messaging. The events carry typed DTOs.
• Extend through contracts rather than forking. Commit message rendering, path filtering, sync strategies, forge clients and health checks are replaceable from a service provider.
• Add statamic:git-sync:doctor to CI or deploy gates. Its non-zero exit status is designed for exactly that.

Gotchas and Tips

• doctor is not optional. Run it after config changes and in deploys; it is the fastest way to catch identity, remote, branch, cache-lock and pull-request misconfiguration.
• If commits happen on every save instead of after the debounce window, check cache lock support first. The fallback is safe but noisier, and doctor should be telling you why.
• Only configured paths are committed. The package uses git commit --only, so files staged by hand stay staged and are not swept into an automated commit. Do not expect it to act like git add -A.
• Nothing is committed during a merge, rebase or cherry-pick. If syncing appears to stop, check repository state before assuming the package is broken.
• Pull/rebase or merge before push can abort on conflict and restore the working tree. That is safer than forcing a push, but it means a successful edit is not necessarily a successful publish; monitor SyncFailed and ConflictDetected.
• Pull-request mode refuses a setup where head and base are the same. Configure a real feature/current branch and a distinct base branch.
• Do not remove the Committed-by: statamic-git-sync trailer from templates. It prevents automated sync commits from feeding back into the sync loop.
• SyncManager::sync() never throws into a control panel save request; the subscriber only queues. Do not build UI error handling around exceptions from content saves. Use events, notifications and the widget/history instead.
• Credentials in remote URLs are redacted from logs and exception messages, but prefer SSH or a credential helper where possible. Redaction is a safety net, not a reason to put secrets in URLs.
• Failure handling is classified: network push failures retry with backoff, missing git binaries and conflicts do not. A conflict needs a person, so do not tune retries expecting it to self-heal.
• Console output is intentionally English even though control panel translations exist for English and German. Keep deploy-log parsing and alerting in English.
• Supported versions are PHP 8.2–8.4 and Statamic 5/6, including Statamic Solo. Check those constraints before adding the package to an older project.