C6 · publish & loop
Point Dock at a repository. It pulls the Markdown and HTML in, mirrors each file as an artifact, and groups them under one collection. The repo stays the source of truth; Dock becomes the readable, shareable, commentable view of those docs for the people who never open the repo. Edits stay in git; the conversation lives in Dock.
GitHub renders Markdown, but it has no story for sharing a rendered doc with a non-dev, commenting on a specific paragraph, or collecting feedback. That gap is the whole feature.
Complement to the publish Action (#111), not a duplicate. The dock-publish GitHub Action is outbound: a CI step that pushes one built artifact up to Dock. This is inbound: Dock reaches into a repo and mirrors many files on demand. Outbound suits a generated report per pipeline run; inbound suits a living /docs tree.
Every box but two already exists. The new code is the GitHub client and the sync engine; the rest is the publish pipeline, collections, the tombstone, and the sandbox we already shipped.
owner/repo, a branch, an include glob, and a read-only token. Dock makes a collection named for the repo.**/*.md, **/*.html), and reads each file's blob SHA.Why it's cheap: steps 04–05 are publish / addVersion, addCollectionItem, and setArtifactRemoved — all shipped and tested. v1 adds only the front of the line: talk to GitHub, diff by SHA, drive the loop.
One new table. v1 deliberately avoids a second mapping table by storing the path→artifact map as JSON on the source row — fine at the scale of a repo's docs, and it keeps the multi-store schema (SQLite · Postgres · D1) with its compile-time parity guard to a single addition.
CREATE TABLE repo_source (
id TEXT PRIMARY KEY,
org_id TEXT NOT NULL DEFAULT 'local',
collection_id TEXT NOT NULL REFERENCES collection(id),
repo TEXT NOT NULL, -- "owner/name"
ref TEXT NOT NULL DEFAULT 'HEAD', -- branch
includes TEXT NOT NULL, -- comma globs: "**/*.md,**/*.html"
token TEXT, -- read-only PAT (null for public repos)
files TEXT NOT NULL DEFAULT '{}', -- JSON: { "docs/intro.md": {artifact_id, sha} }
last_synced_at TEXT,
last_status TEXT, -- "ok" | "error: ..."
created_by TEXT NOT NULL,
created_at TEXT NOT NULL
)Read-only is derived, not a new column. An artifact is "managed" when its id appears in some repo_source.files. The artifact detail response carries a managed flag (one small scan of the few sources), the UI hides Edit/Propose, and the publish/propose handlers reject a managed artifact with 409. No widening of the hot artifact table, no parity churn on the core record.
addCollectionItem per file.removed_at + the 410 render path for deleted files.fail()).managed flag.The one genuinely sensitive part: a personal access token sits in the database.
| Scope | Ask only for read-only repo contents (a fine-grained PAT, Contents: Read). Dock never writes to the repo in v1. |
| At rest | v1 stores the token on the source row. The token is never returned by any read endpoint (redacted to ••• in list responses). Production should encrypt it or move it to the platform secret store — flagged, not yet done. |
| Egress | The client only ever talks to api.github.com / raw.githubusercontent.com over HTTPS — no user-controlled host, so the webhook-style SSRF surface does not apply here. |
| Blast radius | One-way + read-only means a leaked sync can, at worst, read what the token could already read. It can never push to the repo or publish on a user's behalf. |
| Later | Why not in v1 |
|---|---|
| GitHub App + push webhook | Real-time sync on every commit is the right end state, but a PAT + "Sync now" button proves the loop in a fraction of the code. The engine is identical; only the trigger changes. |
| Two-way write-back | Editing in Dock and opening a PR is a separate product with its own auth and conflict model. One-way keeps the source of truth unambiguous. |
| Per-commit history | v1 versions per sync run, not per commit. Mapping the full git history onto artifact versions is a nice depth feature, not a wedge. |
| Monorepo → many collections | v1 is one repo → one collection. Splitting by top-level directory is a config nicety on top. |
| Private-repo billing | A pricing/packaging question, orthogonal to the mechanism. |
The whole feature lands behind one settings section and four endpoints.
POST /v1/sync/github connect: { repo, ref?, includes?, token? } → creates source + collection
GET /v1/sync/github list sources (token redacted) + status + file counts
POST /v1/sync/github/:id/run "Sync now" — runs the engine, returns { added, updated, removed, skipped }
DELETE /v1/sync/github/:id disconnect (keeps the collection + artifacts by default)Settings → GitHub. A connect form (repo, branch, globs, token), then a row per source: repo name, last-synced time, file count, a Sync now button, and disconnect. It mirrors the existing Webhooks / Agents sections, uses the design tokens and data-testids the CI guardrails require, and reports through sonner.