Timestamp GIT

← All posts

2026-10-26

Automate Bitcoin Timestamping for Every GitHub Commit

Automate Bitcoin Timestamping for Every GitHub Commit
timestamp git blockchain proof

Automate Bitcoin Timestamping for Every GitHub Commit

You’ve decided your commits deserve a cryptographic proof of existence. Good. Now comes the boring part: doing it again tomorrow, and the day after, for every repository your team touches.

That’s where most timestamping efforts quietly die. Not because the idea is wrong, but because the manual chore — batching commit hashes, submitting them to a calendar service, babysitting a proof file, committing it back — doesn’t survive contact with a real sprint. If you want to automate blockchain timestamping for GitHub repositories, the timestamp has to be a side effect of git push, not a task someone remembers to do on Fridays.

This article walks through the automated path end to end: one install, a nightly pipeline you never touch, and monitoring that tells you whether the proofs actually landed in Bitcoin.

Why Manual Timestamping Doesn’t Scale

The hard way to timestamp a commit is to do it by hand every time. You’d be responsible for:

  • Deciding which commits are worth stamping (they all are, which is the problem).
  • Batching hashes yourself so you don’t create one Bitcoin transaction per commit.
  • Submitting to a public calendar and tracking the pending proof until it’s confirmed.
  • Storing the resulting proof file somewhere durable and linked to the right commit.
  • Repeating the whole thing tomorrow, and after every force-push, hotfix, and merge train.

Even scripted, that’s a part-time job. Someone has to own the script, the cron runner, the storage location, and the “why is last week’s proof missing” incident. And the moment that person changes teams, the pipeline rots.

The raw OpenTimestamps protocol is genuinely elegant — you can read how it works in OpenTimestamps Alternative: Managed GitHub App for Every Commit. This article is about the other problem: making it run unattended, forever.

The goal is set-and-forget: every commit to a monitored repository gets anchored nightly, with no developer intervention and nothing installed on anyone’s laptop.

One-Time Setup: Install the GitHub App

Timestamp GIT is a managed service built around a GitHub App. Setup takes minutes and happens once per account or organization.

1. Install the app. From the Timestamp GIT dashboard, install the GitHub App on your personal account or your organization.

2. Select repositories. Choose either all repositories or a specific subset. You can adjust the selection later without reinstalling.

3. Confirm permissions. The permission model is deliberately narrow:

Access Scope Why
Read-only Source repository The GitHub permission system has no “commit hash only” scope, so the app needs read access to see HEAD commit hashes
Read-write Target repository Proofs are written back as manifest files and .ots receipts on a dedicated branch or a shadow repository

4. Walk away. There is no YAML to add, no secret to rotate, no CLI to install. Your developers keep committing exactly as they do now; the app reacts to webhooks in the background.

If your repositories are public, the Open Source tier covers this out of the box. Private repositories start at the Pro Agency tier — the pricing breakdown covers which tier fits which team shape.

The stricter alternative: Enterprise ZK mode

Standard mode requires read access to your source repo. If your policy forbids that — or you simply don’t want any third party able to read your code — Enterprise ZK mode flips the direction. Instead of pulling, your side pushes: a 12-line GitHub Action runs on your own infrastructure and sends only the commit hash to the Timestamp GIT API. Your source never leaves your environment, and the service needs no read access to the source repository at all. Only the target repo (where proofs are written) needs write access.

The Automated Pipeline: From Commit to Bitcoin

Here’s what happens after setup, without you doing anything.

1. Commit detection. New commits arrive either through the GitHub App’s webhooks (standard mode) or through hashes pushed by your GitHub Action (Enterprise ZK mode).

2. Hash queue. Commit hashes land in an in-memory key-value store and wait for the nightly batch. Note what is not in that store: your code. Only hashes.

3. Midnight cron worker. Once a night, a worker:

  • Groups all pending hashes.
  • Builds a per-repository manifest (.txt).
  • Constructs a Merkle tree natively over the batch.
  • Generates OpenTimestamps proofs against public OTS calendars.
  • Anchors the Merkle root into the Bitcoin blockchain.

4. Proof delivery. The manifest and .ots receipt files are pushed back into your repository — either on a dedicated timestamps branch alongside your code or into a separate shadow repository.

Timing expectations. Bitcoin does not confirm instantly. The anchoring transaction typically confirms in roughly three hours, so expect proofs to appear a few hours after midnight UTC. If you’re checking at 00:05 UTC and seeing nothing, nothing is wrong.

The API surface for custom workflows

The pipeline runs itself, but the API lets you wire proof data into your own tooling. All endpoints are authenticated where noted.

# Last anchored Bitcoin block for a repository (public)
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api

# Total stamped commits (public)
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api

# Combined summary, handy for Shields.io
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

# Full Merkle chain data for a specific day, for local verification
curl -s https://timestampgit.dev/api/verify/acme/payments-api/2026-10-25

# Audit ledger as CSV
curl -s -o audit.csv https://timestampgit.dev/api/audit/acme/payments-api

# PDF certificate for one date
curl -s -o certificate.pdf https://timestampgit.dev/api/report/acme/payments-api/2026-10-25

Enterprise ZK installations also use the HMAC-authenticated commit endpoint, where {hash} is the HMAC value returned by the signed URL your Action requests:

curl -X POST \
  "https://timestampgit.dev/api/timestamp/acme/payments-api/timestamps/<hmac>/<commitId>"

That’s the whole integration surface. There is no “start a batch” call to schedule — batching is the service’s job.

Monitoring and Failure Handling

Automation you don’t monitor is just optimism. Timestamp GIT gives you three independent ways to confirm the pipeline is healthy.

The public status dashboard

Each repository gets a public dashboard at /status/{user}/{repo} showing:

  • Proof longevity and the earliest anchor date — how far back your chain of proof reaches.
  • Daily regularity, rendered as a calendar heatmap, so a missed night is visually obvious.
  • Bitcoin block and transaction data for each anchor.

Verification badges

Embed a Shields.io badge in your README to make the proof public:

![Timestamped](https://timestampgit.dev/api/statusSummary/acme/payments-api)

The /connected/{user}/{repo} page gives you a badge embed widget with a live preview, including the markdown snippet. For private repositories, the status URLs carry an encrypted HMAC that is specific to the server instance — status stays visible only to people who have the signed link.

Self-hosted health check

Because the status endpoints are plain JSON, a small script in your own CI catches a stalled pipeline before an auditor does:

import requests

BASE = "https://timestampgit.dev"
USER, REPO = "acme", "payments-api"

r = requests.get(f"{BASE}/api/statusLast/{USER}/{REPO}", timeout=15)
r.raise_for_status()

last = r.json()  # last anchored Bitcoin block info for this repository
print(last)
# Compare against yesterday's stored value in your own job to detect a stalled batch.

What if a nightly batch doesn’t complete? The observable signal is the same in every case: the heatmap shows a gap and the last anchored block stops advancing. Because anchoring is batched by day, a missed run is visible within 24 hours rather than at audit time — and because the hash queue and the manifests are keyed by date, a re-run produces a distinct, dated proof rather than an ambiguous one. Check the dashboard first, then the repository’s timestamps branch to confirm whether the manifest and receipts were written.

The audit trail

For compliance reviews, two artifacts do the heavy lifting:

  • GET /api/audit/{user}/{repo} — the full ledger as CSV.
  • GET /api/report/{user}/{repo}/{date} — a PDF certificate for a single date.

And when someone wants to check the math rather than trust a PDF, the /verification/{user}/{repo}/{date} page walks through the multi-level Merkle chain step by step. All of that computation happens locally in the browser — nothing about what you verify is sent to the server.

Best Practices for Automated Timestamping

Once the pipeline is running, a few habits keep the evidence useful:

  • Commit early and often. Every commit is a data point for prior art. Squashing a month of work into one commit right before a filing gives you one anchor instead of forty.
  • Keep proofs on their own branch. The automated timestamps branch is machine-written; leaving it separate from feature branches keeps git log readable and avoids merge noise.
  • Verify periodically, not just at dispute time. Spot-check a recent date through the web verifier every quarter. Discovering a broken verification chain during litigation is a bad time to discover it.
  • Ship proofs with releases. Attach the manifest and receipts for your release date to your release artifacts, and reference the date in your legal documentation.
  • Tag anything you might patent. Commits are captured automatically; the moment you start discussing a patentable idea, make sure the work is committed rather than sitting in a local branch.

Self-Hosted Automation with Docker

Managed hosting is the default, but some environments can’t use it: air-gapped networks, strict data-residency requirements, or internal policy that forbids any external service touching repository metadata.

For those, Timestamp GIT ships as a Docker image. The automation is identical — the same nightly batching, Merkle tree construction, and Bitcoin anchoring, just running in your infrastructure.

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 once it’s up. On first launch, a setup wizard walks you through connecting your GitHub App and configuring the instance.

To evaluate before you commit, request a time-limited demo license from the Docker License page — name, company, email, and an optional phone number. A time-limited demo license file is available for download, and you upload it during the on-premises setup phase.

FAQ

Do I need to run any commands or install tools on my developers’ machines? No. Timestamp GIT works entirely via the GitHub App. Once installed, every commit to a monitored repository is automatically timestamped nightly. No CLI tools, no OpenTimestamps commands, no manual steps.

How long does it take for a commit to be timestamped? Commits are batched and anchored once per night. The Bitcoin transaction typically confirms within about 3 hours, so proofs are usually available a few hours after midnight UTC.

Can I verify the timestamp independently without trusting Timestamp GIT? Yes. The .ots receipt files can be verified using standard OpenTimestamps tools against the Bitcoin blockchain. The proof relies only on SHA-256 and Bitcoin block data, so you can verify offline even if our service disappears.

What if I need to keep my source code completely private? Use Enterprise ZK mode: a GitHub Action on your infrastructure pushes only the commit hash to our API. We never have read access to your source code. Alternatively, self-host with Docker for full control.

Does the timestamping pipeline touch my source code? No. Standard mode reads commit hashes; Enterprise ZK mode never sees your repository content at all. The service only ever handles SHA-256 hashes and Bitcoin block data.

The Timestamp You Don’t Have to Think About

The value of cryptographic prior art comes from coverage, not from a single impressive proof. One stamped commit from a heroic afternoon proves almost nothing; eighteen months of nightly anchors prove a timeline. That’s a volume problem, and volume problems are solved by automation.

That’s the entire pitch for Timestamp GIT: install the GitHub App once, pick your repositories, and let the nightly job do the rest. Proofs land on a timestamps branch, badges land in your README, and the audit CSV is there when legal asks. If you need isolation, Enterprise ZK mode or Docker gets you there without giving up the automation.

Install the app, push a commit, and check the dashboard tomorrow morning.


Related posts

EU label: AI-generated content