↻ / SYNC
The repository is the source of truth.
This site renders Cobalt Cockpit’s documentation, version, options, commands and history from echelong/cobalt-cockpit on the server. Nothing is copied into the site’s own code, so a change in the repository appears here without a redeploy.
What is read, and how often
| What | From | Re-checked |
|---|---|---|
| Branch head and recent commits | GitHub REST API (commits on main); the commits Atom feed if the API refuses | every sync interval |
| Published releases | GitHub REST API (releases, drafts dropped); the releases Atom feed if the API refuses | every sync interval |
| Tags | GitHub REST API (tags); the tags Atom feed if the API refuses | every sync interval |
| README, docs/, CHANGELOG, SECURITY, PRIVACY, LICENSE, notices | raw.githubusercontent.com at the exact commit of the branch head | once per commit |
| Plugin manifest, marketplace manifest | .claude-plugin/plugin.json and marketplace.json at that commit | once per commit |
| Documentation images | docs/assets at that commit, served through the site | once per commit |
| The page list | the git tree at that commit, grouped by docs/README.md | once per commit |
The sync interval is 300 seconds. Pages are regenerated in the background (incremental static regeneration): the first visit after the interval receives the page as it was and starts a fresh render, and the visits after it receive the fresh page. In practice a change on main is visible within about five minutes of the next visit. Files are read by commit, so one page never mixes two revisions.
When GitHub is slow, limited or down
- Every upstream answer is classified: missing, rate-limited, bad status, timeout (10 seconds), too large or malformed. Only a status-200 answer is ever cached.
- If the REST API refuses or fails, the branch head, releases and tags are read from GitHub’s public Atom feeds instead.
- If a fresh render still cannot complete, it is abandoned and the last successfully rendered page keeps being served. The bar at the bottom of every page then shows how old that copy is, and says “may be out of date” beyond three intervals.
- A document that is deleted from the repository returns 404 here after the next render; a renamed heading falls back to a link to the whole page.
- Draft releases are never shown, whoever’s token reads them. A commit is never treated as a release.
For operators
No variable is required. Three are optional, all read on the server only:
- GITHUB_TOKEN
- A read-only token. Unauthenticated, the REST API allows 60 requests an hour per address; the Atom fallback covers what that limit refuses. A token raises it to 5,000.
- GITHUB_WEBHOOK_SECRET
- Turns on
POST /api/github/webhookfor immediate refresh. Add a webhook on the repository with this secret, content type application/json, and the push and release events (create and delete for tags, optionally). Deliveries are verified with HMAC-SHA256 over their raw bytes before the body is parsed; only events about echelong/cobalt-cockpit act, and a push only for main. - SYNC_REVALIDATE_SECONDS
- The interval, 300 by default. The test suite lowers it; production should leave it alone.