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.

Each delivery is acted on once. Snipfire remembers each delivery's ID and contents for an hour: the same delivery sent again in that time, with its ID or a new one, is answered Delivery already received; ignored. A GitHub push that's more than an hour old is answered Delivery is too old; ignored. This stops a captured delivery from being replayed. One side effect: GitHub's Redeliver button does nothing within an hour of the original delivery. To sync again, click Sync now.

GitLab sends its secret token as it is, without a signature, so keep your site on HTTPS. A webhook can only ever start a sync of the configured branch.

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.