Sites & git connections

A site is the unit everything else in Norcube CMS hangs off: one connection from your organisation to one GitHub repository on one branch. Pages, media, schema, discussions, and version history all scope to a site. This page covers the lifecycle of that connection — creating a site, wiring it to GitHub, keeping its clone fresh, and tearing it down.

What a site is

A site stores a connection, not content. The row holds your organisation, a chosen GitHub installation, a repo (owner/name), and a branch. The content itself stays in your repo — Norcube never keeps a content database. The service mints short-lived installation tokens to read and write on your behalf, and mirrors the branch to a working clone for fast reads.

One organisation can host as many sites as you like, including several pointed at different repos under the same GitHub account. Sites are listed under CMS in the dashboard and are isolated from each other: schema, media, and permissions never cross between them.

Each site carries:

Creating a site

Creating a site is a two-step wizard. Step one commits the site row: pick a name and a slug. That's all the create form needs — provider defaults to GitHub and branch defaults to main, both carried through until you connect a repo.

A freshly created site is in a "pending connection" state. It exists, but it has no repo yet, so the content endpoints (config, tree, files, media) return 409 Conflict until you finish step two. The dashboard, settings, and schema areas still open; they just show "not connected" until the repo is wired up.

Connecting GitHub

Content access runs through the Norcube CMS GitHub App. Connecting a repo means picking an App installation, a repo that installation can reach, and a branch.

The wizard's step two branches on what you already have:

• You already have an installation. The CMS lists the GitHub accounts your org has previously installed Norcube on, grouped by account, with each account's accessible repos. Pick a repo, confirm or change the branch (it pre-fills with the repo's default branch), and finish. No redirect to GitHub needed.
• No installation yet. Click Connect GitHub. You're sent to github.com to install the App, choose which repos it can access, and grant it, then returned to the CMS to pick a repo and branch.

There's also an escape hatch for the awkward case where the App is already installed but GitHub's install page has nothing to redirect back for. Authorize GitHub to list my installations runs a user-to-server OAuth flow: you grant Norcube permission to read /user/installations, and the CMS enumerates every installation you can reach so you can pick a repo directly. The OAuth token is held in memory for that one request and never stored.

What the App can access

The Norcube CMS GitHub App requests repository contents (read and write, so it can read your files and commit edits) and pull_requests. Both are scoped to the repos you pick when you install it — nothing else in your account is visible. These permissions are set on the App registration on GitHub, so the exact grant is what GitHub shows you on the install screen.

The two-step model

Creating the site row and connecting the repo are deliberately separate calls. The row is created first; the connect call then validates that the chosen installation can actually see the named repo before it persists the connection — a repo the installation can't reach is rejected. Until the connect call succeeds, content endpoints answer 409.

The site dashboard

The dashboard is the site's one-glance health view. It shows:

• Stat tiles — total pages, total collections, the current branch, and a live/offline sync indicator.
• Repo + latest commit — the connected owner/name, the branch, and the most recent commit on the working clone (author, subject, short SHA, relative time). The repo name and the SHA link out to GitHub.
• View on GitHub — opens the connected repo in a new tab.
• Continue where you left off and Recent activity — recently edited files and a live feed of clones, pulls, AI runs, and writes.
• Quick actions — jump to Pages, Media, Schema, Members, Settings.

When your repo has no .norcube/cms/ schema yet, the dashboard shows an Analyze repo call-to-action that kicks off the AI scaffold — see AI schema generation.

Keeping the clone in sync

The CMS mirrors your branch to a server-side working clone. Reads (tree listings, file opens, search) hit that local disk instead of GitHub's API, which is what makes them fast. Writes still go through GitHub's APIs and commit straight to your branch.

The clone refreshes two ways:

• Automatically, on push. The App's push webhook fires whenever a commit lands on a connected branch (whether from the CMS, from your own git push, or from a merge). The CMS drops its cached config for that repo and branch and pulls the clone so the next read reflects the new tree.
• On demand. The Pull from git button in site settings pulls the clone immediately. Use it when a push landed outside Norcube and you want the catch-up now, or on a local/dev setup where the webhook isn't wired. It returns once the pull finishes, then re-reads the config with the cache bypassed so the fresh file isn't masked by a stale cached copy.

The site layout also warms the clone the moment you open a site, so even pages that don't otherwise touch the content tree (dashboard, schema, settings) start the clone early.

Searching the repo

Each site has a repo-wide file search: it walks the whole working clone and returns files whose name matches your query (case-insensitive substring), newest first. You can restrict the walk to a subdirectory, filter by extension, and optionally pull each Markdown file's frontmatter inline so the results can show preview titles. This powers the search box on the Pages list and is distinct from the folder-scoped tree listing.

Renaming, re-slugging, and deleting

Rename / re-slug

Editing a site's name or slug updates the Norcube-side labels only. The slug must stay URL-safe (lowercase letters, digits, and dashes, 1-64 characters, starting and ending alphanumeric). Renaming doesn't touch the repo or the git connection.

Delete

The settings Danger zone permanently removes the site from Norcube. Deleting requires typing the site's slug to confirm, and the card only shows for callers who hold the delete permission.

Delete removes the Norcube connection and all CMS-side state for the site — its collections, pages, media records, drafts, discussions — and wipes the server-side working clone. It does not touch your GitHub repository or its files. The clone wipe is best-effort and never blocks the delete; your content stays exactly where it is in git, so you can reconnect the same repo later as a fresh site.

Members

A site's Members area controls who in your organisation can work on that specific site and what they can do. Access is delegated per site: inviting a member and viewing policies run through Norcube's permissions system rather than the CMS content APIs. See Permissions for the roles and capabilities.

What's not there yet

• GitHub only. gitlab is reserved as a provider name, but no GitLab adapter ships today — the install, OAuth, and connect paths all reject anything that isn't GitHub. GitLab and other hosts are follow-on work.
• No in-place branch switching. You choose the branch when you connect the repo. There's no settings control to repoint an existing site at a different branch yet.
• Installation lifecycle is partial. If you remove the App from a repo on GitHub, the CMS drops its cache for the affected repos, but a site still pointing at a removed installation isn't automatically marked disconnected yet.

Where to next