xeiaso.net
Git backed by object storage because you can't stop me
git
object-storage
kefka
1# Push hooks
2
3`objgitd` can run a script after a successful push. The script lives **inside the
4repository** at `.objgit/hooks/receive-pack` and runs in a restricted, in-process
5shell — not a real operating-system shell. This document describes how to enable
6hooks, what a hook can and cannot do, and how to write one.
7
8## Enabling hooks
9
10Hooks are off by default. Start the server with `-allow-hooks`:
11
12```text
13./objgitd -bucket $BUCKET -allow-push -allow-hooks
14```
15
16| Flag | Env | Default | Meaning |
17| --------------- | -------------- | ------- | -------------------------------------------------------- |
18| `-allow-hooks` | `ALLOW_HOOKS` | `false` | Run `.objgit/hooks/receive-pack` after a successful push |
19| `-hook-timeout` | `HOOK_TIMEOUT` | `60s` | Wall-clock limit for a single hook run |
20
21`-allow-hooks` is independent of `-allow-push`, but a hook can only fire on a
22push, so in practice you want both.
23
24## When a hook runs
25
26- **On push only.** The hook is named after the git service that triggered it,
27 and the only service that runs a hook is `receive-pack` (push). Fetches,
28 clones, and archives never run hooks.
29- **After the push completes.** Refs are already updated and the client has
30 already received its response when the hook starts. A hook therefore **cannot
31 reject a push** and its output is never shown to the person pushing — it goes
32 to the server log only. This is a post-receive hook, not a pre-receive gate.
33- **Once per changed branch.** If a push updates or creates several branches,
34 the hook runs once for each, with environment variables describing that
35 branch (see below). Branch **deletions** are skipped (there is nothing to
36 check out).
37- **Asynchronously.** The push returns immediately; the hook runs in the
38 background. On server shutdown, in-flight hooks are given a short grace period
39 to finish.
40
41The script is read from the **commit that was just pushed**, so a hook travels
42with the branch — different branches can carry different hooks, and updating a
43hook is just another commit.
44
45## The execution environment
46
47Hooks run in [kefka](https://xeiaso.net/blog/2026/dancing-mad-sandboxing/), a
48virtual `bash` interpreter. **This is not a container, VM, or OS sandbox.** It is
49safe because of what it _cannot_ reach, not because of kernel isolation:
50
51- **No system binaries.** Only kefka's built-in commands exist — roughly the
52 POSIX coreutils: `cat`, `ls`, `echo`, `printf`, `head`, `tail`, `cut`, `sort`,
53 `uniq`, `wc`, `tr`, `grep`, `sha256sum`, `base64`, `mkdir`, `cp`, `mv`, `rm`,
54 `touch`, `date`, `sleep`, `seq`, `expr`, and so on. There is no `git`, no
55 package manager, no compiler, no `curl`.
56- **No network.**
57- **No host filesystem.** The only files a hook can see are the two mounts
58 below.
59
60Standard `bash` syntax works: variables, `if`/`for`/`while`, pipes,
61redirections, command substitution, `[ ... ]` tests, and `&&`/`||`.
62
63### Filesystem layout
64
65| Path | Contents | Writable? |
66| ------ | --------------------------------------------------------------- | ------------------ |
67| `/src` | The pushed commit, checked out. The shell starts here (`$PWD`). | **No** — read-only |
68| `/tmp` | Empty scratch space. Also `$HOME` and `$TMPDIR`. | Yes |
69
70`/src` is a live, lazy view of the git tree: files are fetched from object
71storage as they are opened, so nothing is copied to disk up front. Everything
72under `/src` is **read-only**. Writing scratch data — including shell
73redirections like `echo x > out` — must target `/tmp`.
74
75> **Important:** a redirection into a read-only path _aborts the script_. For
76> example `echo hi > /src/note.txt` does not merely fail that one line; it stops
77> the hook with a "read-only filesystem" error. Always redirect into `/tmp`.
78
79### Environment variables
80
81Each run gets variables describing the branch that triggered it:
82
83| Variable | Example | Notes |
84| ---------------- | ----------------- | --------------------------------------------------- |
85| `OBJGIT_REPO` | `/myproject.git` | Repository path |
86| `OBJGIT_SERVICE` | `receive-pack` | Always `receive-pack` |
87| `OBJGIT_REF` | `refs/heads/main` | Full ref name |
88| `OBJGIT_BRANCH` | `main` | Short branch name |
89| `OBJGIT_OLD_SHA` | `0000…0000` | Previous tip; all zeros when the branch was created |
90| `OBJGIT_NEW_SHA` | `f43417…` | New tip |
91
92For compatibility with scripts written for stock git, the same information is
93also fed on **stdin** as a single `<old> <new> <ref>` line.
94
95## Writing a hook
96
97Put the script at `.objgit/hooks/receive-pack` in your repository and commit it.
98The executable bit is not required — `objgitd` reads the file's contents, not its
99mode.
100
101```bash
102#!/usr/bin/env bash
103# .objgit/hooks/receive-pack
104
105echo "push to ${OBJGIT_REPO} ${OBJGIT_REF}: ${OBJGIT_OLD_SHA} -> ${OBJGIT_NEW_SHA}"
106
107# /src is the checkout of the new commit; the shell starts there.
108echo "top-level contents:"
109ls /src
110
111# Read a file out of the push.
112if [ -f /src/go.mod ]; then
113 module="$(head -n 1 /src/go.mod | cut -d' ' -f2)"
114 echo "go module: ${module}"
115fi
116
117# Scratch work goes in /tmp.
118manifest=/tmp/manifest.txt
119echo "ref ${OBJGIT_REF}" > "${manifest}"
120echo "sha ${OBJGIT_NEW_SHA}" >> "${manifest}"
121cat "${manifest}"
122
123echo "hook done"
124```
125
126A copy of this example lives at
127[`.objgit/hooks/receive-pack`](../../.objgit/hooks/receive-pack) in this
128repository.
129
130## Observing hooks
131
132All hook activity is logged through the server's structured (`slog`) logger:
133
134- `hook: running` — a hook started, with `repo`, `service`, `ref`, and `sha`.
135- `hook: finished` — success, with the hook's `exit` code, captured `stdout`,
136 and `stderr`.
137- `hook: finished with errors` — the hook exited non-zero, failed to parse, hit
138 the timeout, or tried to write somewhere read-only. The error is attached
139 under the `err` key.
140- `hook: no hook file in pushed tree` (debug level) — the push had no
141 `.objgit/hooks/receive-pack`, so nothing ran.
142
143Because output is log-only, a hook cannot communicate back to the client that
144pushed.
145
146## Limitations
147
148- No writable working tree: `/src` is strictly read-only and `/tmp` is the only
149 scratch space.
150- No way to reject a push from a hook (it runs after the fact).
151- No system tooling, network, or arbitrary executables — only kefka built-ins.
152- Output is not relayed to the pusher.