{"id":34599172,"url":"https://github.com/flyingrobots/shiplog","last_synced_at":"2026-04-21T00:03:57.125Z","repository":{"id":315741452,"uuid":"1060619650","full_name":"flyingrobots/shiplog","owner":"flyingrobots","description":"Stop digging through dashboards. Shiplog turns your Git repo into a cryptographically-signed, append-only ledger for every deployment. Zero SaaS costs. Zero external infra. Just Git.","archived":false,"fork":false,"pushed_at":"2025-10-22T08:43:25.000Z","size":993,"stargazers_count":0,"open_issues_count":35,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-10-22T10:23:09.773Z","etag":null,"topics":["automation","changelog","ci-cd","deployment","devops","git","gitops","ledger","logging","observability","zero-infra"],"latest_commit_sha":null,"homepage":"","language":"Shell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/flyingrobots.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-09-20T08:52:17.000Z","updated_at":"2025-10-22T00:43:56.000Z","dependencies_parsed_at":"2025-09-20T13:08:00.503Z","dependency_job_id":"638b0764-5d43-47f8-be8b-28a4f4a587f6","html_url":"https://github.com/flyingrobots/shiplog","commit_stats":null,"previous_names":["flyingrobots/shiplog"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/flyingrobots/shiplog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fshiplog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fshiplog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fshiplog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fshiplog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/flyingrobots","download_url":"https://codeload.github.com/flyingrobots/shiplog/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/flyingrobots%2Fshiplog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28002250,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-12-24T02:00:07.193Z","response_time":83,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["automation","changelog","ci-cd","deployment","devops","git","gitops","ledger","logging","observability","zero-infra"],"created_at":"2025-12-24T12:07:36.817Z","updated_at":"2025-12-24T12:07:51.390Z","avatar_url":"https://github.com/flyingrobots.png","language":"Shell","funding_links":[],"categories":[],"sub_categories":[],"readme":"# 🚢🪵 Shiplog — Git‑Native Deployment Ledger\n\n\u003cimg alt=\"shiplog\" src=\"https://github.com/user-attachments/assets/3c4d88fd-f46e-46f2-83ee-cc761ffdf9ef\" height=\"500\" align=\"right\" /\u003e\n\nRemember that 2 AM incident where no one knew which version was deployed or who changed the config? _(We've ruled out Jenkins... For now.)_\n\nYou spent hours digging through Slack threads and ephemeral CloudWatch logs trying to piece together what went wrong.\n\nThat's because your deployment logs live in dashboards you don't control, in formats you can't query, already rotated out.\n\n**Shiplog fixes that.**\n\nIt turns your Git repo into a **cryptographically signed, append-only ledger** of every step of every deployment. It's not another workflow; Shiplog is the **deployment primitive**. Think of it like a `git commit`, but for deployments. **Keep your existing workflows!**\n\nRun anything with:\n\n```bash\ngit shiplog run \u003cyour-command\u003e\n```\n\nShiplog captures **stdout, stderr, exit code, timestamp, author, and reason**—everything you'd normally lose—and logs it in a signed, immutable ref right inside Git. Who/What/Where/When/Why/How; mystery solved. Deployment **logs now live with your codebase, but apart from it**. Provenance without clutter.\n\nA built-in **allow list enforces policy at the source**: only trusted contributors can deploy, or multiple parties can sign off before a **quorum** is met. Every run is verified. Every log is auditable. Every action is permanent.\n\n**Zero SaaS. Zero external infra. Zero guesswork. Policy as infrastructure, living right alongside your code.**\n\n---\n\n## Highlights\n\n- **Git All the Way Down**: No new databases, no SaaS. All data lives under Git refs in your own repository.\n- **Human \u0026 Machine-Readable**: Clean TTY views for humans and script-friendly structured output (`--json`, `--json-compact`, `--jsonl`).\n- **Policy as Code**: Allow lists, per-environment requirements, and signature rules are stored and enforced directly in Git.\n- **Multi-Sig Trust**: Choose between **Chain** (commit signatures) or **Attestation** (SSH -Y verify) for your required signing quorum.\n\n---\n\n## Quick Start\n\n### 1. Install once on your workstation or CI runner.\n\n```bash\n# Clone and set up the environment\ngit clone https://github.com/flyingrobots/shiplog.git \"$HOME/.shiplog\"\nexport SHIPLOG_HOME=\"$HOME/.shiplog\"\nexport PATH=\"$SHIPLOG_HOME/bin:$PATH\"\n\n# Install dependencies (mostly jq) and verify\n\"$SHIPLOG_HOME/install-shiplog-deps.sh\"\ngit shiplog --version\n```\n\n### 2. Initialize and Log\n\nInitialize Shiplog in your repository and record your first entry.\n\n```bash\ncd your-repo\ngit shiplog init\n\n# Set environment variables for the deployment context\nexport SHIPLOG_ENV=prod SHIPLOG_SERVICE=web\n\n# Option A: Capture a command run\ngit shiplog run --service deploy --reason \"canary\" -- \\\n  kubectl rollout status deploy/web\n\n# Option B: Manually write a journal entry (will prompt for metadata and enforce policy)\ngit shiplog write \n\n# Publish explicitly when ready (pushes journals, notes, policy, and trust refs)\ngit shiplog publish --env prod\n```\n\n\u003e [!tip]  \n\u003e **Non-interactive/CI Tip**: Pass required fields via flags or environment variables to avoid prompts.\n\u003e ```bash\n\u003e SHIPLOG_ENV=prod SHIPLOG_SERVICE=web \\\n\u003e git shiplog --boring --yes write --status success --reason \"first ci run\"\n  \n### 3. Browse History\n\nReview the deployment history with clean TTY or structured output.\n\n```bash\ngit shiplog ls --env prod\ngit shiplog show --json-compact      # Single entry, compact JSON\ngit shiplog export-json              # NDJSON stream for dashboards\n```\n\n---\n\n## 🛠️ Requirements\n\nShiplog uses stock POSIX tooling. Ensure the following minimum versions are available:\n\n| Tool | Minimum Version | Why it matters |\n|------|-----------------|----------------|\n| `git` | 2.35+ | Leans on modern refspec handling and `git ls-remote`/`update-ref`. |\n| `bash` | 5.0+ | All helper scripts target `bash` (strict mode, mapfile, heredocs). |\n| `jq` | 1.7+ | Policy validation and structured output. | \n| `ssh-keygen` | OpenSSH 8.2+ | Required for attestation mode (`ssh-keygen -Y verify`). |\n\n\u003e [!tip]  \n\u003e Running `install-shiplog-deps.sh` (as done in the Quick Start) will install or upgrade `jq` for you.\n\n---\n\n## ⚙️ Configuration \u0026 Policy\n\nPrefer to plan your policy first? Use the interactive config wizard.\n\n```bash\n# Prints a plan; add --apply to write policy/config\ngit shiplog config --interactive\n\n# Emits example GitHub Rulesets to stdout\ngit shiplog config --interactive --emit-github-ruleset\n\n# Emits a CI verify workflow to stdout\ngit shiplog config --interactive --emit-github-workflow\n```\n\n---\n\n## How It Works: Ref Structure\n\nShiplog stores all its data in lightweight Git refs, separate from your main code branches.\n\n- **Journals**: `refs/_shiplog/journal/\u003cenv\u003e` (The append-only deployment history)\n- **Policy**: `refs/_shiplog/policy/current` (Allow lists and rules)\n- **Trust**: `refs/_shiplog/trust/root` (Root of the trusted signers/keys)\n- **Notes**: Attachments (e.g., logs) under `refs/_shiplog/notes/logs` are associated with journal entries.\n\nPolicy resolution merges CLI/env overrides, local repo config, the policy ref, and working fallbacks. See [`docs/features/policy.md`](./docs/features/policy.md).\n\n---\n\n## Multi-Sig Trust Modes\n\nChoose how maintainer approval is expressed. Both are supported.\n\n### 1. Chain (`sig_mode=chain`)\n\n- Maintainers co-sign trust commits. The policy requires a threshold of distinct signers over the same trust tree.\n- **Pros**: Fully Git-native, excellent audit trail.\n- **Cons**: Maintainers must sign trust commits (often via a dedicated workflow).\n\n### 2. Attestation (`sig_mode=attestation`)\n\n- Maintainers sign a canonical payload (tree OID + context); verified via `ssh-keygen -Y verify`.\n- **Pros**: Flexible; easier to automate with SSH keys/CI.\n- **Cons**: Requires additional artifact handling; precise canonicalization matters.\n\n**Fast Pick**: Use chain if your maintainers are comfortable signing commits. Use attestation when signatures primarily come from automation or dedicated SSH keys.\n\n\u003e [!important]  \n\u003e See [`docs/TRUST.md`](./docs/TRUST.md) for bootstrapping and verifier details.\n\n---\n\n## Git Hosts \u0026 Enforcement\n\n| Host Type | Enforcement Strategy | Recommended Ref Namespace |\n|-----------|----------------------|-------------|\n| GitHub.com (SaaS) | Use Branch/Push Rulesets + Required Status Checks. | SaaS does not run custom server hooks. Prefer a branch namespace (`refs/heads/_shiplog/**`) so rules apply. |\n| Self-hosted (GH Enterprise, GitLab, Gitea) | Install the pre-receive hook (`contrib/hooks/pre-receive.shiplog`) to enforce policy/trust server-side. | The default ref namespace (refs/_shiplog/**) is fine. Switching namespaces is supported via `scripts/shiplog-migrate-ref-root.sh` and `git config shiplog.refRoot`. |\n---\n\n## What’s Live vs Roadmap\n\n### Live Now\n\n- Journals (append-only by env) with human + JSON views.\n- Policy/trust refs; allow lists by env; threshold verification.\n- Two trust modes (chain, attestation) + shared verifier script.\n- Core commands: `run`, `write`, `append`, `ls`, `show`, `export-json`, `publish`.\n- Hosting docs: GitHub SaaS guidance and self-hosted hooks; enforcement matrix.\n- Dockerized cross-distro tests and CI linting/validation.\n\n### Roadmap (Short-term)\n\n- Setup Questionnaire improvements and emitters (Rulesets + CI snippets per host).\n- Attestation E2E fixtures across distros.\n- Flip CI linters to blocking after baseline cleanup.\n\n---\n\n## Contributing \u0026 Tests\n\n- Please read [`AGENTS.md`](./AGENTS.md) before running tests or editing hooks/scripts.\n- **Run tests inside Docker**: `make test` (optionally: `TEST_TIMEOUT_SECS=180 make test`).\n\n\u003e [!warning]\n\u003e Do not run Bats directly on your host!\n\u003e Shiplog tests perform destructive Git operations, and it's essential they run in isolation to avoid clobbering your host's Git setup.\n\n---\n\n## FAQ\n\n| Question | Answer |\n|----------|--------|\n| What is AJV and why does CI mention it? | AJV is a fast JSON Schema validator for Node.js. CI uses it to validate `.shiplog/policy.json` against its schema. Locally, `git shiplog policy validate` performs `jq` checks. |\n|Can Shiplog enforce policy on GitHub.com (SaaS)? | Yes, but via **Branch/Push Rulesets + Required Checks** and a branch namespace for Shiplog refs, as SaaS doesn't run custom server hooks. | \n| Which trust mode should I use? | **Chain** if maintainers can sign commits; **attestation** if signatures come from automation/SSH. Both are fully supported. | \n\n## License\n\nMIT • © J. Kirby Ross • [flyingrobots](https://github.com/flyingrobots)\n\n_Jenkins was not harmed in the making of this project._\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fshiplog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fflyingrobots%2Fshiplog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fflyingrobots%2Fshiplog/lists"}