--- title: Adding a Collection description: "GitHub collections are part of the Premium and Agency plans. ## Supported URL formats GOCSM accepts the following GitHub URL formats: ``` https://github.com/user/repo https://github.com/user/repo/tree/branch https://github.com/user/repo/tree/branch/path/to/subdir github.com/user/repo user/repo ``` The plugin normalizes HTTP and shorthand forms to GitHub HTTPS URLs, strips…" url: "https://brightleafdigital.io/docs/adding-a-collection/" updated: "2026-10-20" category: GravityOps Code Snippet Manager / Github Collections --- # Adding a Collection GitHub collections are part of the Premium and Agency plans. ## Supported URL formats GOCSM accepts the following GitHub URL formats: ``` https://github.com/user/repo https://github.com/user/repo/tree/branch https://github.com/user/repo/tree/branch/path/to/subdir github.com/user/repo user/repo ``` The plugin normalizes HTTP and shorthand forms to GitHub HTTPS URLs, strips the GitHub UI prefix, and constructs the raw content URL automatically. SSH URLs and non-GitHub URLs are rejected. ## What the repository must contain At the root of the import path (the repo root, or the subdirectory if you specified one), there must be a `snippets.json` manifest file. See [Creating Your Own Snippet Library](04-creating-your-own-snippet-library.md) for the manifest format. ## Private repositories To sync a private repository, define a GitHub token in `wp-config.php`: ``` define( 'GOCSM_GITHUB_TOKEN', 'github_pat_...' ); ``` Use a fine-grained personal access token with **read-only Contents** access, limited to the repositories you sync. The token applies site-wide to every GitHub collection, so all private collections on the site must be readable by it. Public repositories keep working with the token set. There is no admin setting for the token. Keeping it in `wp-config.php` keeps it out of the database, exports, and the admin screens. ## Import flow 1. Go to the **Collections** tab. 2. Select **GitHub repository** as the source type. 3. Paste the URL and optionally enter a branch override or display name. 4. Click **Add Collection**. 5. GOCSM fetches the manifest, validates it, then fetches each snippet file, verifying its hash. 6. Uniquely matching existing standalone snippets are adopted automatically; unmatched snippets are saved as inactive. 7. Tags, config rows, and collection metadata are stored during the import. 8. A sync log entry is created for the import. If the initial manifest fetch or manifest validation fails, GOCSM deletes the temporary collection record and shows the error. If an individual snippet fails to fetch or its hash does not match, that snippet is logged and skipped, and the collection is kept. A repository URL that is already added is rejected. During later syncs, individual snippet fetch or hash failures are logged and skipped; the previous snippet version remains in place. ## Automatic adoption of existing snippets Adding a collection, or syncing one that introduces new snippets, checks this site's GOCSM standalone snippets and Code Snippets records before creating anything. You do not need to import Code Snippets first. A unique match becomes collection-managed automatically: - **GOCSM standalone:** keeps its existing ID, activation or error state, configuration values, execution scope and priority, folder, tags and revision history. Existing shortcode references keep working because the ID stays the same. The repository supplies the managed source, name, description, version and update identity. Environment requirements retain the stricter existing minimums and required plugins. - **Code Snippets:** moves directly into GOCSM with its supported scope mapping, priority, tags and declared config values. Active originals get an active replacement; inactive originals remain inactive. After preparation succeeds, the original is deactivated and retained for recovery. The origin mapping prevents a later Code Snippets overwrite import from detaching the collection snippet. - **Already imported:** the GOCSM copy and its recorded Code Snippets original count as one candidate. If the original still runs, their effective code, configuration and mapped scope must agree before the handoff. Matching uses code and type, never the title alone. For PHP, opening tags, comments and ordinary formatting may differ. Valid literal values inside recognized config blocks may differ for PHP, JavaScript and CSS, provided the declarations and remaining code match. JavaScript, CSS and HTML otherwise require exact source matching; whitespace and line breaks can affect behavior. Values hardcoded elsewhere, older versions with changed logic, missing config markers, duplicate candidates and ambiguous collection entries require review rather than guessed conversion. Trashed snippets are excluded. The Collections screen and sync log report adopted snippets and review reasons. A conflict leaves the original untouched and does not create a second copy. Resolve the differences or trash unwanted duplicates, then use **Sync Now** to retry; conflict retries fetch the manifest again even if its repository version has not changed. Adoption also runs for new snippets discovered by background sync. Direct Code Snippets HTML snippets that use numeric `[code_snippet id="..."]` references require the existing **Import → Code Snippets** flow with shortcode migration first. Sync the collection afterwards: GOCSM can then adopt the imported record without changing its new ID. Network-wide Code Snippets records are outside this site's import scope. Active replacements are validated and generated before their originals are stopped. Ownership and configuration changes use a database transaction; failed handoffs roll back, restore the original activation if needed, and remove the unused replacement file. Automatic adoption requires InnoDB tables for this rollback guarantee. Collection syncs serialize adoption across repositories so two collections cannot claim the same standalone snippet concurrently. ## Managing a collection Each row in the collections table shows the collection's **Health**, including the number of consecutive failed syncs. After three consecutive failures (including an invalid manifest) the collection is marked unhealthy and the button reads **Retry Sync**. - **Sync Now** / **Retry Sync** — check the repository immediately. - **Edit** — change the display name, the branch override, and auto-update. Changing the branch makes the next sync fetch the manifest fresh. - **Delete** — removes the collection together with all of its snippets, their configuration values, and their generated files. This cannot be undone. ## Custom collections Select **Custom (manual)** as the source type to create a non-syncing collection record. Current custom snippets created from **Add New** are standalone snippets with no collection assignment, and no screen assigns a snippet to a custom collection; only [importing](../02-managing-snippets/06-import-and-export.md) can place snippets in one. GitHub-sourced snippets remain read-only and are managed by their collection.