Automatic sync, webhooks and WP-CLI Agency plan

Agency · Git sync is part of the Agency plan (and its free trial). Plans

You can always click Sync now (in the editor's Git sync view or on the Tools page). There are three ways to sync without clicking.

On a schedule #

In the Git sync settings, set Sync automatically to Every hour, Twice a day or Once a day. It uses WP-Cron, so on a quiet site it runs on the next page view after the time comes. If your host runs WP-Cron from a real cron job, it's on time.

The Git sync view shows Also syncs automatically. when a schedule is set.

Instantly on every push: webhooks #

A webhook tells your site about each push, so a change in Git reaches the site within seconds.

On the Tools page, under Webhook, you'll find the Payload URL and the Secret (the secret is made when you first save the settings):

https://example.com/wp-json/snipfire/v1/git/webhook

GitHub: repository → Settings → Webhooks → Add webhook:

• Payload URL: the URL above
• Content type: application/json
• Secret: the secret from WordPress
• Which events: Just the push event

GitLab: project → Settings → Webhooks → Add new webhook:

• URL: the URL above
• Secret token: the secret from WordPress
• Trigger: Push events

The webhook only acts on pushes to the branch you sync, and only when they're signed with your secret (GitHub's X-Hub-Signature-256, GitLab's X-Gitlab-Token). Anything else is refused. It needs no WordPress login.

On servers running PHP-FPM, the site answers GitHub or GitLab first and then syncs in the same request; elsewhere the sync runs through WP-Cron straight away (or on the next page view).

Make a new secret replaces the secret: update it in the repository's webhook settings afterwards.

The webhook needs your site to be reachable from the internet. For local development sites, use the schedule or WP-CLI instead.

WP-CLI #

wp snipfire git setup --provider=github --repo=acme/snippets --branch=main \
    --root=snipfire --scope=Shared --schedule=hourly --token=github_pat_… --check
wp snipfire git check                     # test the connection
wp snipfire git sync                      # sync now
wp snipfire git sync --format=json        # with the full report
wp snipfire git status                    # settings, last sync, conflicts
wp snipfire git resolve <uid> --keep=git  # settle a conflict (or "all")
wp snipfire git reset                     # forget the last sync

setup only changes the options you pass. Use --remove-token to delete a saved token, and --api= for GitHub Enterprise Server or self-managed GitLab. Full reference: WP-CLI.

In a deploy script #

Run a sync after deploying, so the site picks up snippet changes merged in the same release:

wp snipfire git sync || echo "Git sync reported a problem"

REST API #

For tools that can't run WP-CLI: POST /wp-json/snipfire/v1/git/sync (full access). See REST API.

Only one sync at a time #

If a sync is already running (from a schedule, a webhook and a click at once), the second one stops with A sync is already running. Try again in a minute.