---
title: How GitHub Sync Works
description: "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…"
url: "https://brightleafdigital.io/docs/how-github-sync-works/"
updated: "2026-10-20"
category: GravityOps Code Snippet Manager / Github Collections
---

# How GitHub Sync Works

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](02-adding-a-collection.md#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.

1. Fetch `snippets.json` from each GitHub-sourced collection, sending an `If-None-Match` header with the stored ETag if available. A `304 Not Modified` response means nothing changed — the check takes milliseconds.
2. If a new manifest is returned, validate it and update the collection metadata.
3. For each snippet in the manifest, compare its `version` and `hash` to the stored `source_version` and `source_hash`.
4. For changed snippets, fetch the new source, re-verify the hash, sync tags, and compute a config-variable diff.
5. 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.