Automatic Git Commit Timestamping Without Any CLI
Most teams that want cryptographic prior art never get it, and the reason is almost never technical. It’s operational. A timestamping habit only works if a human remembers to run the tool on the right commit, at the right moment, and store the receipt somewhere the auditor will find it eighteen months later. Under deadline pressure, that habit dies first.
This article is about removing the habit entirely. Not “how to run a timestamping command more often,” but how to make every commit in a monitored repository get anchored to the Bitcoin blockchain automatically, every night, with zero commands typed by anyone on your team. If you’re evaluating whether the raw protocol is worth learning versus using a managed GitHub App, we cover that trade-off separately in OpenTimestamps vs Timestamp GIT: Manual Proofs or GitHub App?. Here we assume you’ve decided you want the automation.
The Manual Timestamping Trap (And Why You Want Out)
Picture how manual timestamping actually plays out:
- Someone finishes a feature branch and remembers — usually after the fact — that this commit should be timestamped.
- They run a tool, wait, and get a receipt file back.
- The receipt gets renamed, dropped in a
proofs/folder, committed, or worse, emailed to a manager. - Nobody does this for the next forty commits because the sprint got busy.
The raw OpenTimestamps CLI exists and is the hard way to do this: it’s an expert-oriented path where you own the batching, the proof files, the calendar interaction, and the filing system. It works. It also depends on a person being disciplined forever, and it leaves no audit trail explaining why commit 4f9c1ab has a proof and commit 8d2e0f3 doesn’t.
The compliance failure mode is worse than the inconvenience. A prior-art record with holes in it is a record a lawyer can pick apart. If a counterparty asks “prove what your codebase looked like on the 14th of March,” and your answer is a spreadsheet plus a developer’s memory, you’ve already lost the framing. Manual processes are also hard to audit: there’s no consistent artifact, no regular cadence, and no way for a compliance reviewer to confirm coverage without asking engineers to reconstruct their own history.
The automation promise is different in kind, not degree: install once, and from that moment every commit to a monitored repository is fingerprinted and anchored nightly. No CLI to learn, no receipts to file by hand, nothing installed on developer machines. The proof record becomes a property of the repository rather than a property of someone’s diligence.
One-Time Setup: Install the GitHub App and Forget It
The primary path is the GitHub App. You install it on a repository or on the whole organization, and the setup is genuinely one-time — no per-repository scripts, no developer onboarding step.
Standard Mode (GitHub App). The App reads the HEAD commit hash of each monitored repository automatically. GitHub’s permission model doesn’t offer a “commit hash only” scope, so the App requires at least read-only access to the source repository. It also needs read-write access to the target repository, because that’s where proofs are written: a dedicated timestamps branch, either in the same repository as the source or in a separate shadow repository.
Enterprise ZK Mode. A 12-line GitHub Action runs on your own infrastructure and pushes only the commit hash to the Timestamp GIT API. In this mode the service needs no read access to the source repository at all — only read-write access to the target repo for proof delivery — and you install the Action in your workflow. Choose this when source-code read access is a non-starter for policy reasons, or when your security review requires that hashes originate inside your perimeter. Choose Standard mode when you want the absolute minimum moving parts.
| Standard (GitHub App) | Enterprise ZK (GitHub Action) | |
|---|---|---|
| Source repo access | Read-only | None |
| Target repo access | Read-write | Read-write |
| Where hashes originate | The App | Your CI runner |
| Setup effort | Install the App | Install the App + add the Action |
In both modes, nothing is installed on developer machines. Engineers keep committing exactly as they do today, and the whole pipeline runs server-side. The service never sees, copies, or stores your source code — it only ever handles commit hashes.
If you need to run the whole thing inside your own network, Timestamp GIT is also available as a self-hosted Docker image. A quick-start Docker Compose setup looks like this:
services:
timestampgit:
image: rue1401/timestampgit:prod
ports:
- "8080:8080"
volumes:
- ./data:/app/data
restart: unless-stopped
valkey:
image: valkey/valkey:8
restart: unless-stopped
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
The application is available at http://localhost:8080 after startup, and a first-launch setup wizard walks you through connecting your GitHub App and configuring the instance. A time-limited demo license for evaluation can be requested from the Docker License page. We go deeper on deployment in Self-Host Git Timestamping With Docker Compose.
The Automated Pipeline: From Commit to Bitcoin Anchor
Once the App is installed, here’s what happens without you:
- Commit detection. Either the GitHub App picks up new commits via webhooks, or your GitHub Action pushes commit hashes to the API. Only hashes move.
- Hash queue. Commit hashes land in an in-memory key-value store, waiting for the nightly batch.
- Midnight cron worker. Each night, a worker groups all pending hashes, writes a manifest text file per repository, builds a Merkle tree natively, creates OpenTimestamps proofs using public OTS calendars, and anchors the Merkle root into the Bitcoin blockchain.
- Proof delivery. The manifest and the
.otsreceipt files are pushed back into your repository — a dedicated timestamps branch or a shadow repository — so the proofs live next to the code they describe.
One practical timing note: Bitcoin confirmation takes several hours, normally around three. So a commit made on Tuesday ends up with a finalized proof on Wednesday morning, not Tuesday night. That’s the cost of anchoring into a public, immutable ledger, and it’s a cost worth paying.
You don’t have to take any of this on faith. Every monitored repository gets a public status dashboard showing proof longevity, earliest anchor date, daily regularity, the Bitcoin block and transaction data behind each anchor, and a calendar heatmap you can eyeball for gaps. The same page offers downloadable audit CSV and PDF certificates. Verification itself happens at /verification/{user}/{repo}/{date}, which walks the multi-level Merkle chain step by step — and all of that computation happens locally in the browser, so nobody sees what you verify.
For READMEs, embeddable badges publicly display verification status, and anyone can follow the badge link to verify the timestamp on the site or download the PDF report.
To wire status into your own dashboards, the public API is deliberately boring:
# Last anchored Bitcoin block info
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api
# Total committed/stamped commit count
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api
# Combined summary (what the Shields.io badge consumes)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api
And when compliance asks for artifacts, don’t click through a UI at 5pm on a Friday:
# Full audit ledger as CSV
curl -sL -o audit-acme-payments-api.csv \
https://timestampgit.dev/api/audit/acme/payments-api
# PDF certificate for a specific day
curl -sL -o certificate-2026-11-14.pdf \
https://timestampgit.dev/api/report/acme/payments-api/2026-11-14
Badge URLs and ready-to-paste markdown come from /api/badgeLink/{user}/{repo} (authenticated). For private repositories, status URLs carry an encrypted HMAC specific to your server instance, so only authorized users can read them.
Monitoring and Failure Handling: Keeping the Automation Honest
Automation you don’t watch is automation you don’t know is working. Three things are worth building a habit around.
Watch for gaps, not for errors. If a nightly run fails, the system retries, and pending hashes stay in the in-memory queue rather than being dropped. But queue depth and retries are internal; the calendar heatmap on the status page is the thing you can actually read. A missing day is visible immediately as a hole in the grid.
Poll and alert. A small scheduled job that compares the latest status payload against yesterday’s snapshot will catch a stalled pipeline before an auditor does:
import json, pathlib, requests
REPO = "acme/payments-api"
URL = f"https://timestampgit.dev/api/statusSummary/{REPO}"
snapshot = pathlib.Path("last-status.json")
r = requests.get(URL, timeout=30)
r.raise_for_status()
current = r.json()
previous = json.loads(snapshot.read_text()) if snapshot.exists() else None
if previous == current:
print("WARNING: status unchanged since last poll - check the repo status page")
else:
print("new anchor data:", json.dumps(current))
snapshot.write_text(json.dumps(current, indent=2))
Run it hourly in CI, or daily right after the cron window, and route the warning somewhere humans look.
Plan audits around confirmation delay. Because anchoring into Bitcoin takes a few hours after the cron worker runs, “timestamp everything from last night’s release, I need the certificate in ten minutes” is not a request anyone can satisfy. Give compliance a simple rule: proofs for day N are final by day N+1.
The reassuring part of failure handling is what happens if the service is unavailable entirely. Verification does not require us. The .ots receipt file can be checked offline against the Bitcoin blockchain using standard OpenTimestamps verification tools, because the proof depends only on SHA-256 and Bitcoin block data — no proprietary technology, no lock-in. Even if the vendor disappears, the proof stands.
Best Practices for Hands-Off Timestamping
- Commit early and often. Every commit is automatically fingerprinted, so a dense commit history produces a dense prior-art record. Squashing a month of work into one commit the night before a patent filing gives you one anchor instead of two hundred.
- Pick the mode that matches your security posture. If source-repo read access is off the table, use Enterprise ZK mode: only commit hashes leave your infrastructure, pushed by the GitHub Action.
- Export audit ledgers and certificates on a schedule. Compliance archives shouldn’t depend on someone remembering a download link. Hit
/api/audit/{user}/{repo}monthly and/api/report/{user}/{repo}/{date}for milestone dates, and store the results wherever your legal artifacts live. - Put the badge in your README. Beyond the signal it sends to customers, a live verification badge is a cheap deterrent against “we independently developed this” claims.
- Keep proofs in their own branch or shadow repo. Daily proof commits landing in a dedicated timestamps branch keep your main history readable while keeping the evidence attached to the same repository.
- Write down the process. For an auditor, document who installed the GitHub App, which repositories are monitored, and where the timestamps branch lives. The math is verifiable; the chain of custody still needs a paragraph.
FAQ
Do I need to install any software on developer machines?
No. Timestamp GIT is a managed service that runs entirely server-side via a GitHub App. Developers just commit as usual; no CLI tools or local installations are required.
How long does it take for a commit to be timestamped?
Commits are batched nightly and anchored into Bitcoin. The Bitcoin confirmation typically takes around 3 hours, so proofs are usually available a few hours after the nightly cron runs.
Can I verify proofs without the service?
Yes. You receive an immutable .ots receipt file that can be verified offline using standard OpenTimestamps tools against the Bitcoin blockchain. The proof is vendor-independent and relies only on SHA-256 and Bitcoin block data.
What if I use a private repository?
The GitHub App works with private repositories. Status URLs for private repos include an encrypted HMAC specific to your server instance, so only authorized users can view the status.
Conclusion
The whole value of a prior-art record is that it exists when you need it, which means it can’t depend on a human remembering a command. Install the GitHub App once, and every commit in the monitored repositories is queued, batched at midnight, Merkle-rooted, and anchored into Bitcoin — with proofs pushed back into a branch you own, a status dashboard you can check, and CSV and PDF exports for the auditors.
If the reason you haven’t timestamped your code is that it always looked like a chore, that reason just went away. Start at timestampgit.dev — connect a repository, let the first nightly batch run, and look at the calendar heatmap the next morning.
Related posts
- OpenTimestamps vs Timestamp GIT: Manual Proofs or GitHub App?
- Self-Host Git Timestamping With Docker Compose
- Cryptographic Prior Art: The Startup Shield Against Patent Trolls