|
| 1 | +# Shiplog DX Notes — September 2025 |
| 2 | + |
| 3 | +I took Shiplog for a (manual) spin today in order to integrate it with the PF3 deploy orchestrator. These are the rough notes I’d want any future maintainer to have — both what felt rock-solid and what I’d polish next. |
| 4 | + |
| 5 | +--- |
| 6 | + |
| 7 | +## Overall Impression |
| 8 | + |
| 9 | +Shiplog already feels *production ready* for the git-native audit log niche it targets. The primitives — signed commits under `refs/_shiplog/journal/<env>` with structured trailers — map perfectly onto the “what happened in prod?” question we ask ourselves during incidents. Once trust/bootstrap is in place, `git shiplog write` feels just as natural as `git commit`. |
| 10 | + |
| 11 | +I’d happily depend on it for: |
| 12 | + |
| 13 | +- Deploy receipts (start → step → finish) |
| 14 | +- Maintenance mode toggles (with reasons / reminders) |
| 15 | +- RBAC changes (added admin, revoked key) |
| 16 | +- Trust rotations & secret rotations |
| 17 | +- Ad-hoc scripts with log capture (once `shiplog run` lands) |
| 18 | + |
| 19 | +In other words: if an operator does something that changes prod, Shiplog is the canonical place to record it. That’s exactly what I want from an operational journal. |
| 20 | + |
| 21 | +--- |
| 22 | + |
| 23 | +## Things That Felt Great |
| 24 | + |
| 25 | +- **Git-first workflow**: No extra service. Journals are just refs. Easy to mirror, easy to inspect. |
| 26 | +- **Signing/Policy hooks**: Guard rails are strong. Missing trust ref immediately fails with a helpful message. SSH signing plays nicely with modern git. |
| 27 | +- **Structured trailers**: The JSON we get back from `git shiplog show --json` is deliciously parseable. Perfect for piping into dashboards or incident bots. |
| 28 | +- **Trust tooling**: `shiplog-bootstrap-trust.sh` + `shiplog-trust-sync.sh` made the initial setup straightforward. Non-interactive flags mean we can script it. |
| 29 | +- **Docs/AGENTS discipline**: The repo has clearly codified expectations (test in Docker, etc.). Easy to onboard to. |
| 30 | + |
| 31 | +--- |
| 32 | + |
| 33 | +## Opportunities / DX Wishlist |
| 34 | + |
| 35 | +### 1. `git shiplog run` (on deck) |
| 36 | +Exactly what we’re about to build: wrap a command, tee stdout/stderr, and attach the log as a note. I’d ship it with: |
| 37 | +- `--service`, `--reason`, `--status-success/failed` overrides. |
| 38 | +- Structured `run` payload: `argv`, `cmd`, `exit_code`, `status`, `duration_s`, `started_at`, `finished_at`. |
| 39 | +- Boring mode by default; interactive tee for humans. |
| 40 | +- Respects `SHIPLOG_NAMESPACE`, `SHIPLOG_TICKET`, etc., so we can categorize maintenance vs deploy vs misc. |
| 41 | + |
| 42 | +### 2. Programmatic API helper |
| 43 | +Either a `git shiplog append --json payload` or a tiny shell helper that sets `SHIPLOG_EXTRA_JSON` and calls `write`. That would keep deploy-orchestrator code simpler. |
| 44 | + |
| 45 | +### 3. Namespace defaults |
| 46 | +`git shiplog ls` shows `Env` as `?` unless `SHIPLOG_NAMESPACE` is set. Defaulting the namespace to the journal name (or providing a `--namespace` flag) would make the table friendlier. |
| 47 | + |
| 48 | +### 4. Trust roster visibility |
| 49 | +A `git shiplog trust show` command that prints threshold and maintainer list would be handy during audits. |
| 50 | + |
| 51 | +### 5. Docs: runbook for operators |
| 52 | +Once `shiplog run` is available, a short runbook (“How to log maintenance mode”, “How to record an incident”, “How to rotate trust”) would accelerate adoption. |
| 53 | + |
| 54 | +--- |
| 55 | + |
| 56 | +## Integration Notes (PF3) |
| 57 | + |
| 58 | +For PF3 we intend to: |
| 59 | +- Emit a Shiplog entry when a deploy plan is approved (status=started + plan JSON). |
| 60 | +- Append entries after each step (`status` `in_progress`, `reason` summarizing action, structured run payload). |
| 61 | +- Finish with a `status=success|failed` entry containing maintenance flag, failure reason, etc. |
| 62 | +- Use `shiplog run` for ad-hoc maintenance toggles or recovery scripts so we capture raw command output automatically. |
| 63 | + |
| 64 | +That will replace our ad-hoc JSON journal with a tamper-evident history. |
| 65 | + |
| 66 | +--- |
| 67 | + |
| 68 | +## Misc Observations |
| 69 | + |
| 70 | +- **Trust bootstrap** refused to run outside a repo. Nice guard! Perhaps the script could detect this earlier and print “run inside target repo” with the resolved path. |
| 71 | +- **Preview output** always prints (even in `--yes`). I like that, but a `SHIPLOG_NO_PREVIEW=1` toggle might be nice for CI logs. |
| 72 | +- **`SHIPLOG_EXTRA_JSON`** hook was easy to splice in once I noticed trailers are composed in `compose_message`. Reusing `shiplog_json_escape` will keep it tidy when I refactor the helper. |
| 73 | +- **Testing** via `make test` (Docker) was smooth. Love that the AGENTS doc shouts *not* to run tests directly. |
| 74 | + |
| 75 | +--- |
| 76 | + |
| 77 | +## Other Potential Use Cases |
| 78 | + |
| 79 | +- **Incident timeline**: `git shiplog run --service incident --reason "Declared SEV-1" -- env true` to mark major steps. |
| 80 | +- **Access review**: Append entries whenever someone is added/removed from Supabase roles or GitHub teams. |
| 81 | +- **Secrets rotation**: Wrap rotation scripts with `shiplog run` so we have an audit trail of the exact CLI output. |
| 82 | +- **Schema migrations**: Each `supabase db push` could be wrapped to capture the migration log. |
| 83 | +- **Build provenance**: If we wanted to record Docker image builds (“built ghcr.io/app@sha…”) we could make `shiplog run` a standard part of the release pipeline. |
| 84 | + |
| 85 | +--- |
| 86 | + |
| 87 | +## Closing Thoughts |
| 88 | + |
| 89 | +Shiplog is already delivering on the “black box recorder for ops” promise. The biggest DX win on the horizon is the command wrapper — once we have that, we can eliminate a ton of bespoke logging code across projects. Happy to help keep pushing it forward! |
| 90 | + |
0 commit comments