Git hooks

Bare-repo git hooks are how the push pipeline (S14) gets called. shithub installs pre-receive (gates) and post-receive (enqueue) on every repo. Both are tiny shell shims that exec into the same shithubd binary the web/SSH/worker layers run.

Why shell shims and not direct binary symlinks

git invokes hooks with stdin piped, a particular cwd, and a controlled env. The shim normalizes the entry point: exec /path/to/shithubd hook <name>. Hooks aren't symlinked because (a) macOS git treats some symlinks oddly under hardened runtime, and (b) the shim explicitly re-exec's so signals and exit codes propagate cleanly.

The shim is regenerated on every hooks.Install call — there's no manual editing path, by design. If the binary moves (deploy upgrade, versioned install path), run shithubd hooks reinstall --all to point every repo at the new location.

Hook execution flow

git push  ──▶  receive-pack
              │
              ▼
         pre-receive  (one process per push)
              │ stdin: "<old> <new> <ref>" lines
              │ env:   SHITHUB_USER_ID / _USERNAME / _REPO_ID / _REPO_FULL_NAME
              │        SHITHUB_PROTOCOL / _REMOTE_IP / _REQUEST_ID
              ▼
         exec shithubd hook pre-receive
              │ exit 0 → accept
              │ exit ≠ 0 → reject; stderr is shown to the pusher
              ▼
       (push proceeds)
              │
              ▼
         post-receive  (one process per push)
              │ stdin: same shape
              ▼
         exec shithubd hook post-receive
              │ INSERT push_events row per ref
              │ INSERT job (push:process)
              │ NOTIFY shithub_jobs
              │ exit 0
              ▼
       worker picks it up via LISTEN

pre-receive contract

Implements the minimum gates described in S14. The full branch protection engine is S20.

Re-checks the following from the DB even though the env carries them (env can be stale on a long-lived SSH session):

• User not suspended (users.suspended_at IS NULL).
• Repo not archived (repos.is_archived = false).
• Repo not soft-deleted (repos.deleted_at IS NULL).

Failures emit a shithub: ... line on stderr that git surfaces directly to the pusher's terminal. Latency budget: <100ms p99.

post-receive contract

• Reads stdin, ignores empty/malformed lines.
• For each <old> <new> <ref> line: INSERT a push_events row, then enqueue a push:process job carrying the new event id.
• Issues a single NOTIFY shithub_jobs per push (workers wake on the next tx commit).
• Exits 0 even on internal errors. The push has already landed; the pipeline is async — partial enqueue failures surface in the worker logs and a backstop reconciler (post-MVP) can re-process orphaned events.

Installation

• On repo create (internal/repos/create.go::Create): runs hooks.Install after RepoFS.InitBare succeeds. The S11 plumbing initial commit does not fire hooks — that's correct, the contract is hooks fire on user-driven pushes only.
• On deploy: shithubd hooks reinstall --all walks every active repo via the DB and re-installs. Single repos: --repo owner/name.
• The binary path baked into the shim is os.Executable() of the running shithubd at install time, resolved through filepath.Abs. Test fixtures that don't exercise hooks pass ShithubdPath: "" to repos.Create.Deps to skip installation.

Failure modes worth knowing

• SHITHUB_* env not set (e.g. someone manually triggered a push via a path that bypassed S12/S13): pre-receive returns the "missing context" error. post-receive logs a warning and exits 0 — the push still lands.
• DB unreachable from hook: pre-receive returns "server error"; the user sees a generic message, the push aborts. post-receive logs and exits 0; backstop reconciler will pick up the unprocessed push on next opportunity.
• Binary path drift between install and execution: the shim's hard- coded path no longer exists. git will report "hook execution failed" and abort the push. Operators recover with hooks reinstall.
• Stale shim from previous shithubd version: Install is idempotent and overwrites; re-running on a deploy is the right move.

Deferred: hook DB role split

S14's spec calls for the hook to connect with a least-privilege Postgres role distinct from the one the web server uses. S14 ships the dev path (single role) and defers the split to S37 deploy automation. The full GRANT recipe and the planned config plumbing live in db-roles.md, and the bullet is on the S37 deliverables list so it doesn't fall off.