Troubleshooting Git sync Agency plan

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

Start with Test the connection on the Tools page (or wp snipfire git check). The last sync's result is shown as Last sync … OK or Failed with the message. Messages are listed here as the plugin shows them; "GitHub" reads "GitLab" if that's your host.

Connection and token #

GitHub refused the access token. Check that it's correct and hasn't expired. The token is wrong, was revoked, or expired. Create a new one (setup) and enter it.

The access token doesn't allow this. It needs read and write access to the repository's contents. On GitHub, the fine-grained token needs Contents: Read and write for this repository. On GitLab, the project access token needs the api scope and at least the Developer role. For an organisation's repository, check the organisation allows the token.

Connected to acme/snippets, but the access token can only read it. Syncing needs write access too. Same fix as above: give the token write access.

Repository acme/snippets wasn't found, or the access token can't see it. Check the spelling of Repository (owner/name), and that the token was given access to this repository. Private repositories look "not found" to tokens that can't see them.

Couldn't reach GitHub: … Your server couldn't connect. It's usually temporary; if it persists, your host may block outgoing connections: ask them to allow api.github.com or gitlab.com (or your self-hosted address).

GitHub's limit on requests was reached. The next sync will try again. Too many API requests in a short time. Wait; the next sync continues.

GitHub answered with an error (HTTP …). Something unexpected on the host's side. The text in brackets is the host's own explanation.

The saved access token can't be read any more (the site's secret keys changed). Enter it again. The token is encrypted with a key from your site's secret keys in wp-config.php. They changed (for example after a security reset or a migration), so enter the token again, or put it in wp-config.php.

Settings #

Enter the repository and an access token first. / Set up Git sync first: repository and access token. Fill in both and save.

Enter the repository as owner/name (or paste its web address). For example acme/snippets or https://github.com/acme/snippets.

That isn't a valid branch name. Branch names can't contain spaces or characters like ~ ^ : ?.

The API address must start with https://. Self-hosted GitHub or GitLab must be reached over HTTPS.

During a sync #

A sync is already running. Try again in a minute. A scheduled sync, a webhook or another person started one. Wait a minute.

The branch changed during the sync. Someone pushed while the sync ran, and kept pushing through all three attempts. Sync again.

The repository has too many files for GitHub to list at once. Use a repository (or branch) just for snippets. GitHub can only list a limited number of files in one go, and this repository has more. Keep snippets in a smaller repository or their own branch.

"…" came from Git but is switched off here: … The code in Git has a problem on this site (the message says what). It's saved, but off, and the site keeps running. Fix it in Git (or on the site) and sync. See Code from Git that fails.

… has the same snippet ID as …, so it was ignored. Give each snippet its own settings file. Two settings files in the repository have the same uid, usually because a file was copied. Give the copy a new uid.

… has no code file next to it (…), so that snippet was left alone. A settings file's code file is missing, or has a different name or extension. Rename them to match (name.json and name.php), with the extension for the snippet's type.

The webhook doesn't fire #

• In the repository's webhook settings, check the delivery log: GitHub and GitLab show each attempt and the answer.
• Invalid signature. (401): the secret in the repository doesn't match the one on the Tools page. Copy it again, or click Make a new secret and update both.
• Not the synced branch.: the push went to another branch. Nothing to do.
• No delivery at all: your site must be reachable from the internet (not a local or password-protected staging site). Firewalls or security plugins may block /wp-json/snipfire/v1/git/webhook.

Git sync isn't in the menu #

• You need full Snipfire access.
• On the Pro plan, the Tools page shows Upgrade to Agency instead: Git sync is part of the Agency plan and the free trial.