How specgit works

Step 1 — Access: a fine-grained GitHub App, repo by repo

All sign-in goes through the specgit GitHub App — there is no separate password and no broad OAuth grant. You (or your organization's admin) choose exactly which repositories the installation can reach, and tokens are short-lived. The App requests four narrow permissions:

• Contents (Read & write) — Read the Markdown and HTML files people open, and save their edits back as ordinary git commits on review branches.
• Pull requests (Read & write) — Open a pull request for each draft, post review comments, and merge when someone publishes.
• Issues (Read & write) — Post and read the discussion comments on those pull requests (GitHub serves PR-level comments through its issues API).
• Metadata (Read-only) — List the repositories the installation grants — the mandatory baseline permission for every GitHub App.

The installation cannot change repository settings, branch protections, or webhooks; manage collaborators, teams, deploy keys, or invitations; reach any repository outside the ones the installation grants. The full permission brief — written for the person who has to approve it — is on the page for IT admins.

Step 2 — Live co-editing: conflict-free, in real time

When you open a document, the editor loads it into a live collaborative document built for conflict-free live editing — any number of people can edit simultaneously without overwriting each other. A real-time collaboration service relays those edits between everyone in the room.

Getting into a room is brokered, not open: the specgit server first verifies — with your own GitHub token — that you can actually access the repository, then mints a short-lived client token for a room whose id is derived server-side from the verified document reference. Clients can never request a token for an arbitrary room, and the browser never holds the realtime server's secret.

Step 3 — Persistence: everything becomes a GitHub primitive

specgit doesn't invent its own storage or review model — it maps every editor action onto the GitHub primitive your engineers already trust:

Branch protection and required reviews work end to end: specgit reads the repository's rules and shows exactly what's blocking a publish ("needs 2 approving reviews — 1 so far") instead of failing mysteriously. Renames are true git renames, so history follows the file.

Mapping onto those primitives is also what makes docs inherit the rest of the repository. Rulesets and CODEOWNERS apply to a doc pull request the way they apply to a code one, the Actions you already run on pull requests run on it (specgit distinguishes "waiting on approval" from "waiting on checks" so the author knows which), history and blame are GitHub's, and in a repository whose pipeline builds a site from the base branch, the merge that publishes a doc ships that site. specgit is not the renderer or the host: the theme, the domain, and reader-facing search belong to the pipeline, not to us.

What this architecture limits by design

The privacy promises on the homepage aren't policy bolted onto a product — they fall out of the architecture:

• specgit never keeps a copy of your documents or comments — GitHub remains the source of truth.
• Product analytics are content-free and processed by PostHog Cloud EU. Restricted or unknown regions send nothing before separate opt-in; elsewhere public events are cookieless and unidentified and signed-in events are pseudonymous with opt-out. No ad tech, sale, or retargeting. See Privacy for retention and rights.
• Your content is never used to train AI models. The optional specgit AI runs only when you invoke it, and every AI-proposed change requires your approval.
• Server logs are metadata only — timings, ids, and counts, never document text.

The full data-handling story — token encryption, retention windows, and what the AI provider sees — is on Security and data privacy.

Frequently asked questions