Automate Git Commit Timestamping With a GitHub App
You’ve decided your commits deserve cryptographic proof of existence. Good. Now the only question that matters operationally is this: does that proof happen when you think about it, or does it happen every night whether anyone thinks about it or not?
The first version of any timestamping process is manual. Someone on the team writes a script, runs it before a release, saves a file somewhere, and feels reasonably protected. Six weeks later that person is on vacation, the script is on a laptop that got reimaged, and the release branch was never stamped at all. Worse, nobody notices — because a repository with partial timestamp coverage looks exactly like a fully covered one until an auditor asks about a specific date.
This article is about the automation path: one install, no per-commit ritual, no tooling on developer machines. We’ll cover the one-time setup, what actually happens between a git push and a Bitcoin block, how to monitor that pipeline, and where automation can quietly go wrong.
The Manual Timestamping Trap (and Why Automation Wins)
Manual timestamping has a predictable failure mode: it scales with discipline, and discipline doesn’t scale across teams, repos, and time zones.
Concretely, the manual approach means running a CLI step or a bespoke script for every commit you care about — or worse, hand-assembling the underlying Bitcoin transaction data. That’s the hard way, and it breaks in three places:
- It’s per-commit. A hundred commits a week becomes a hundred opportunities to skip the step.
- It’s environment-dependent. The script lives on someone’s machine, not in the repo’s story. New hires don’t have it; CI doesn’t have it by default.
- It’s unverifiable as a policy. Compliance can’t tell whether a timestamp is missing because nothing happened that day or because someone forgot.
For developers, the requirement is simple: nothing changes in my workflow. For compliance, the requirement is equally simple: every commit in every monitored repo is covered, and I can prove it.
That’s the case for a GitHub App as the automation surface rather than a CLI. Timestamp GIT’s GitHub App installs once at the organization level, then watches every commit to the repositories you select and anchors them to Bitcoin nightly — long after everyone has gone home.
One-Time Setup: Install the GitHub App and Forget It
Setup is a single pass, done by an admin rather than each developer.
- Install the App on your GitHub organization or personal account.
- Select the repositories to monitor. There is no per-repo configuration file, no CI change, and no developer-machine install.
- Grant permissions. The GitHub permission system doesn’t offer a “commit hash only” scope, so the App needs read-only access to your source repositories and read-write access to the target repository where proofs are written. That read-write target is either a dedicated
timestampsbranch in the same repo or a separate shadow repository — your call. - Done. From here, detection runs via GitHub webhooks and nothing else is required of your team.
If you want the stricter isolation model, Enterprise ZK mode swaps webhook detection for a 12-line GitHub Action that executes on your own infrastructure. That Action pushes only the commit hash to the Timestamp GIT API. In this mode the service requires no read access to your source repositories at all — only read-write access to the target repository that receives proofs. You do, of course, need to install the Action itself.
Self-hosting in an air-gapped or high-security environment
For maximum control, Timestamp GIT ships as a Docker image under a self-hosted license. 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
Bring it up and follow the logs:
docker compose pull
docker compose up -d
docker compose logs -f timestampgit
The application is available at http://localhost:8080 once it starts. On first launch, a setup wizard walks you through connecting your GitHub App and configuring the instance. Evaluation runs on a time-limited demo license, requested via the Docker License page with your name, company, email, and optionally a phone number.
Inside the Automated Pipeline: From Commit to Bitcoin Anchor
Once installed, the pipeline is unremarkable by design. That’s the point — it should be boring.
1. Commit detection. The GitHub App catches new commits via webhooks. In Enterprise ZK mode, your GitHub Action pushes the hashes to the API instead. Either way, only commit hashes move.
2. Hash queue. Hashes land in an in-memory key-value store and wait for the next batch. This is deliberate: batching hundreds of commits into one Bitcoin anchor is what makes the whole thing cheap enough to run on every repository you own.
3. Midnight cron worker. Each night a worker groups all pending hashes, writes a per-repo manifest file (.txt), builds a Merkle tree natively, creates OpenTimestamps proofs against public OTS calendars, and anchors the Merkle root into the Bitcoin blockchain.
4. Proof delivery. The manifest and .ots receipt files are pushed back into your repository — into a dedicated timestamps branch or a shadow repo. Bitcoin confirmation typically takes around 3 hours, so proof writing usually completes a few hours after the batch starts.
The API call that ZK mode makes looks like this (the {hash} segment is the HMAC value from the signed URL, not a commit hash):
curl -X POST \
"https://timestampgit.dev/api/timestamp/acme/payments-api/proofs/<hmac>/<commit-sha>/<commit-id>"
Note what is not in that payload: no diff, no file contents, no branch name, no author identity beyond what a commit ID implies. Zero-knowledge security here isn’t a marketing phrase — the service never sees, copies, or stores your source code, only the Git hash.
And note what is not required of your developers: any command, any hook, any flag. They push as usual. The proof appears the next morning.
Monitoring and Failure Handling: Keeping Your Proofs Reliable
Automation you can’t observe is just hope with extra steps. There are three levels of visibility, and you should use all of them.
Public status dashboards
Every monitored repository gets a status page at https://timestampgit.dev/status/{user}/{repo} showing proof longevity (how far back coverage extends), earliest anchor date, daily regularity, the Bitcoin block and transaction data, and a calendar heatmap. The heatmap is the fastest way to spot a gap: a single missing day stands out immediately.
README badges
Grab the embed widget from https://timestampgit.dev/connected/{user}/{repo}, which gives you a live Shields.io preview plus copy-paste Markdown. The badge links to a public verification page anyone can check — useful when you want a customer or auditor to confirm coverage without creating an account.
# Returns badge URLs and ready-to-paste markdown snippets
curl https://timestampgit.dev/api/badgeLink/acme/payments-api
Private repositories are handled too: their URLs carry an encrypted HMAC, specific to the server instance, so only authorized users can read the status.
Programmatic monitoring and audit exports
The public status endpoints are designed to be polled by your own tooling:
# Last anchored Bitcoin block info (JSON)
curl https://timestampgit.dev/api/statusLast/acme/payments-api
# Total committed / stamped commit count (JSON)
curl https://timestampgit.dev/api/statusCount/acme/payments-api
# Combined summary used by Shields.io
curl https://timestampgit.dev/api/statusSummary/acme/payments-api
For compliance reporting, pull the full audit ledger as CSV with GET /api/audit/{user}/{repo} and per-day PDF certificates with GET /api/report/{user}/{repo}/{date}.
When a run fails
If a nightly run is delayed or fails, pending hashes stay queued and roll into the next batch — commits aren’t dropped on the floor. In practice the symptom of a problem is a flat stretch on the status heatmap rather than lost data. Watch it in two places: docker compose logs -f timestampgit for self-hosted instances, and the dashboard for the SaaS.
Best Practices for Automated Commit Timestamping
Automation removes the per-commit cost, so the right default changes: coverage should be broad, not curated.
- Monitor every repository that contains IP. Cherry-picking “important” repos is a manual decision masquerading as automation — and the repo you skip is always the one that turns out to matter. The marginal cost of another repo is a nightly hash in an existing batch.
- Use Enterprise ZK mode for sensitive codebases. If your policy says commit hashes themselves shouldn’t transit a third party, the GitHub Action route keeps everything but the hash inside your perimeter. For fully isolated environments, the Docker self-hosted license covers the same ground.
- Export audit ledgers on a schedule. A CSV in the same folder as your legal documents beats a dashboard login you’ll forget during a dispute.
- Commit early and often on monitored branches. Many small commits give you a denser proof trail with more defensible dates than one large squash at release time.
- Avoid rewriting history on branches you rely on for prior art. A force-push creates new hashes; the old ones remain anchored, but the mapping between “this code” and “this proof” gets harder to explain to a lawyer. If you must rewrite, tag the pre-rewrite state first.
- Keep the proof branch separate from your source branches. The
timestampsbranch or shadow repo is generated output — treating it as read-only avoids accidental merges intomain.
One boundary to keep in mind: batching plus roughly 3 hours of Bitcoin confirmation means a commit made at 5 p.m. is not provable by 5:05 p.m. If you need proof today, plan around the nightly window rather than expecting instant settlement.
FAQ
Do developers need to run any commands or install tools to timestamp commits?
No. Once the GitHub App is installed, every commit to a monitored repository is automatically detected and anchored to Bitcoin nightly. Developers continue using Git as usual — no CLI, no manual steps.
How long after a commit is the timestamp proof available?
Commits are batched and anchored once per night. After the batch is submitted, Bitcoin confirmation typically takes around 3 hours, so proofs are usually available the next morning.
Can I verify the timestamp without relying on Timestamp GIT?
Yes. The .ots receipt files and Merkle proofs are vendor-independent — SHA-256 plus Bitcoin block data, no proprietary format. You can download them and check them against the Bitcoin blockchain with standard OpenTimestamps tooling, or use the in-browser verification page, which does all computation locally in your browser. That local verification is worth reading up on separately: see How to Verify a Bitcoin Timestamp Proof in Your Browser.
What if my repository is private or contains sensitive code?
Timestamp GIT never reads or stores your source code — only commit hashes are processed. For stricter isolation, Enterprise ZK mode has a GitHub Action push only hashes from your own infrastructure, or you can self-host with Docker. If you’re weighing the trade-offs against other approaches, Timestamp GIT Alternatives: What to Compare First covers the comparison dimensions.
What if I use multiple GitHub organizations?
Install the App on each organization and monitor the repositories you need. Your dashboard aggregates all monitored repositories in one place.
Conclusion
The value of a timestamp is inversely proportional to how much attention it requires. A proof you generate manually is a proof that exists for the commits you remembered — which, in an audit, reads as an inconsistent process rather than a protected one.
Installing the GitHub App takes one admin session. After that, every commit to a monitored repository is hashed, batched, Merkle-rooted, and anchored into Bitcoin while you sleep, with badges for public credibility, CSV ledgers for compliance, and .ots receipts that outlive any vendor. Developers change nothing.
Ready to stop doing it by hand? Install the GitHub App for your organization — free for public repositories, with Pro Agency and Enterprise ZK tiers for private repos and hash-only workflows.
Related posts
- OpenTimestamps Without the CLI: Managed Bitcoin Timestamping
- How to Verify a Bitcoin Timestamp Proof in Your Browser
- How to Timestamp Git Commits Without the Command Line