GitHub collections are part of the Premium and Agency plans.
Trust model #
GOCSM imports from public GitHub repositories out of the box, fetching raw file content over HTTPS from raw.githubusercontent.com using WordPress’s wp_remote_get(). No token is required.
Private repositories need a GitHub token defined as the GOCSM_GITHUB_TOKEN constant in wp-config.php (see Private repositories). When the constant is set, GOCSM fetches every collection through the GitHub Contents API instead, sending the token only to api.github.com and never following redirects with it. The token is never stored in the database, shown in the admin, exported, or written to the Sync Log.
Each snippet’s source file is verified against a sha256:<64 hex chars> hash declared in the manifest. If the fetched file does not match its declared hash, that snippet import or update is skipped. This prevents content from being silently altered between the manifest and the file.
How updates are detected #
GOCSM runs a daily background check (gocsm_check_collections cron event). The first run happens about an hour after activation. Collections marked unhealthy are skipped by the daily check; use Retry Sync on the Collections tab to try them again.
- Fetch
snippets.jsonfrom each GitHub-sourced collection, sending anIf-None-Matchheader with the stored ETag if available. A304 Not Modifiedresponse means nothing changed — the check takes milliseconds. - If a new manifest is returned, validate it and update the collection metadata.
- For each snippet in the manifest, compare its
versionandhashto the storedsource_versionandsource_hash. - For changed snippets, fetch the new source, re-verify the hash, sync tags, and compute a config-variable diff.
- Snippets that no longer appear in the manifest are marked Orphaned. An orphaned snippet stops running, even if it was active, because only active snippets load.
Changes to a snippet’s scope or requires in the manifest apply only when the snippet is first imported. Later manifest changes to those fields are not applied to snippets already on the site.
Background jobs #
| Job | Schedule | What it does |
|---|---|---|
gocsm_check_collections |
Daily | Checks each healthy GitHub collection for updates, as described above. |
gocsm_apply_auto_updates |
Daily | Applies staged None and Info severity updates for collections with auto-update enabled. |
gocsm_prune_sync_log |
Daily | Deletes Sync Log entries older than the retention period set in Settings. |
Update severity #
| Severity | Meaning |
|---|---|
| None | No config variables were added or removed (default values may have changed). Auto-update is safe. |
| Info | New config variables were added. Auto-update is safe; you may want to fill in the new values. |
| Warning | One or more existing config variables were removed. Manual review required. |
Auto-update vs manual #
When Auto-update is enabled on a collection, GOCSM applies Info and None severity updates automatically when it can regenerate any active generated file successfully. Warning-severity updates are always held for manual review, regardless of the auto-update setting.
If auto-update is disabled, detected updates are staged with update_pending = true until an admin reviews and applies them. If an automatic update cannot be applied (for example, the active file cannot be regenerated), it is staged as pending instead.
