Automatically Timestamp Every Git Commit with a GitHub App
Every time you commit, Git already generates a unique hash that identifies the exact state of your repository. That hash is a cryptographically secure fingerprint of your work at that moment. What it is not, by itself, is proof of when the work existed. Turning that hash into immutable, court-ready evidence used to mean a manual process: run extra commands, babysit the output, store receipt files, and repeat for every commit.
The automated alternative is simpler: install a GitHub App once, select your repositories, and let every future commit get anchored to the Bitcoin blockchain while you sleep.
Timestamp GIT is a managed service built around that idea. It fully automates the OpenTimestamps protocol so you never need to touch a CLI, construct a Bitcoin transaction, or manage proof files by hand. This article covers the one-time setup, the nightly automation pipeline, monitoring, best practices, and common questions.
One-Time Setup: Install the Timestamp GIT GitHub App
The whole product is designed around a single setup flow. After that, committing code is the only action you need to take.
Standard Mode: GitHub App
- Install the Timestamp GIT GitHub App from the GitHub Marketplace.
- Grant the permissions requested during installation. In Standard Mode, the app requires read-only access to the source repository because GitHub permissions do not offer a commit-hash-only scope. Timestamp GIT never reads, copies, or stores your source code.
- Select the repositories you want to monitor. Public repositories are supported on the free Open Source plan; private repositories require a paid plan.
- Choose where proof files should live. You can store them in a dedicated
timestampsbranch in the same repository, or in a separate target repository. A separate shadow repository keeps your main source history clean.
After installation, the GitHub App monitors the selected repositories automatically. There are no CLI tools to install, no OpenTimestamps commands to learn, and no manual steps to run after setup.
Enterprise ZK Mode: GitHub Action
For organizations that want maximum isolation, Timestamp GIT offers an Enterprise ZK Mode. Instead of giving the GitHub App read access to your source repository, a GitHub Action runs on your own infrastructure and pushes only the commit hash to the Timestamp GIT API.
The workflow shape looks like this:
name: timestamp-git-zk
on:
push:
jobs:
timestamp:
runs-on: ubuntu-latest
steps:
- name: Push commit hash to Timestamp GIT
env:
COMMIT_SHA: ${{ github.sha }}
REPO: ${{ github.repository }}
run: |
curl -fsS -X POST \
-H "Authorization: Bearer ${{ secrets.TIMESTAMP_GIT_HMAC }}" \
-H "Content-Type: application/json" \
-d "{\"repo\":\"$REPO\",\"hash\":\"$COMMIT_SHA\"}" \
"${{ vars.TIMESTAMP_GIT_API_URL }}"
The exact API URL, repository identifiers, and HMAC secret are provided during the Enterprise setup wizard. The important part is what the workflow does not do: it never sends source code, files, or repository contents. It sends a commit hash and nothing else.
In this mode, Timestamp GIT needs no read access to your source repository at all.
The Automated Pipeline: From Commit to Bitcoin Anchor
Once the GitHub App or GitHub Action is in place, timestamping becomes a background job.
1. Commit Detection
In Standard Mode, the GitHub App receives webhooks when new commits land in your monitored repositories. In Enterprise ZK Mode, your GitHub Action pushes the commit hash to the API directly.
2. Hash Queue
Detected commit hashes enter an in-memory key-value store where they wait for batch processing. Timestamp GIT does not scan your code, clone your full repository, or inspect file contents.
3. Nightly Cron Worker
Each night, a worker groups all pending hashes by repository. For each repository, it creates a manifest file, builds a Merkle tree natively, and creates OpenTimestamps proofs using public OTS calendars.
4. Bitcoin Anchoring
The Merkle root of the daily batch is embedded into a Bitcoin transaction using the OpenTimestamps protocol. Once that transaction is confirmed in a Bitcoin block, the anchor becomes immutable. No entity—including Timestamp GIT—can alter or forge it.
Bitcoin confirmation normally takes around three hours. That means a commit made during the workday is typically anchored by the next morning.
5. Proof Delivery
After confirmation, the manifest and .ots receipt files are pushed back to your configured proof location: either a dedicated timestamps branch or a shadow repository. The proof files are small text and binary files that prove your commit hash existed before the Bitcoin block was mined.
You can query the last anchored block for a public repository with a simple API call:
curl -s https://timestampgit.dev/api/statusLast/your-org/your-repo
The response contains the last anchored Bitcoin block information. Additional endpoints return total stamped commit counts, combined status summaries, and full Merkle chain data for a specific day.
Monitoring and Failure Handling
Automation is only useful when you can see that it is working.
Repository Status Dashboard
Each connected repository gets a public or authenticated status page. The dashboard shows:
- Proof longevity: how far back your earliest anchor date goes
- Daily regularity: whether commits are being batched consistently
- Bitcoin block and transaction data for each anchor
- A calendar heatmap for a visual view of activity
The status page gives you a quick answer to the question: “Did yesterday’s commits get anchored?”
Audit and Compliance Exports
Timestamp GIT provides downloadable audit records:
# Download a full audit ledger as CSV
curl -o audit.csv https://timestampgit.dev/api/audit/your-org/your-repo
You can also download a PDF certificate for a specific date. These exports are useful for compliance archives, legal reviews, or board-level IP documentation.
Handling Missed Commits
In normal operation, a commit that misses the nightly batch—for example, because a webhook delivery was delayed—is picked up in the next nightly run. The batch-oriented design means temporary failures do not require you to re-run anything manually.
Private Repository Privacy
For private repositories, status endpoints are protected with an encrypted HMAC. Only authorized users with the correct URL signature can view repository status. The HMAC is specific to the server instance, so status data is not exposed to the public.
Best Practices for Automated Timestamping
A GitHub App can automate the mechanics, but a few configuration choices make the evidence stronger and easier to manage.
Monitor All Active Repositories
Do not only monitor release branches. Prior art disputes often hinge on an early experimental commit, a work-in-progress branch, or a quick prototype. Enable monitoring on every repository where meaningful code is written.
Use a Dedicated Shadow Repository
If you do not want proof files cluttering your main repository, configure Timestamp GIT to push proofs to a separate repository. This keeps source history clean while still giving lawyers, auditors, and compliance teams a single place to look for proof receipts.
Choose Enterprise ZK Mode for Maximum Isolation
If your code is highly sensitive or your security policy forbids third-party read access to source repositories, use Enterprise ZK Mode. The GitHub Action approach means your source code never leaves your environment. Timestamp GIT only ever receives commit hashes.
Archive Audit CSVs Regularly
The .ots files are the cryptographic proof, but audit CSVs are the human-readable record. Download them on a schedule and store them alongside your other compliance documents. In a dispute, having a clean chronological ledger saves time.
Add Verification Badges to Your README
Public repositories can display a verification badge that links to the Timestamp GIT status page. The repository connection page provides badge URLs and Markdown snippets. A typical badge looks like:
[](https://timestampgit.dev/status/your-org/your-repo)
Anyone viewing the repository can click through and verify the current timestamp status without installing anything.
FAQ
How does the GitHub App timestamp my commits automatically?
Once installed, the GitHub App monitors your selected repositories. Each night, it collects all new commit hashes, creates a Merkle tree, anchors the root into the Bitcoin blockchain via OpenTimestamps, and pushes the .ots proof files back to your repository. No manual steps are required.
Does the GitHub App need access to my source code?
In Standard Mode, the GitHub App requires read-only access to the source repository to read commit hashes, because GitHub permissions require that scope. However, Timestamp GIT never reads, copies, or stores your source code—it only processes the commit hash. In Enterprise ZK Mode, a GitHub Action runs on your infrastructure and pushes only the commit hash to the API, so the app has no access to your source repository at all.
How long does it take for a commit to be timestamped on Bitcoin?
Commits are batched nightly. After the batch is processed, the Bitcoin transaction is broadcast. Confirmation on the Bitcoin blockchain typically takes around three hours, after which the proof files are written to your repository. A commit made during the day will usually have its timestamp proof available the next morning.
Can I verify the timestamp without relying on Timestamp GIT?
Yes. The proof is a standard OpenTimestamps .ots file. You can download it and verify it locally using any OpenTimestamps verification tool against the Bitcoin blockchain. Timestamp GIT also provides a web-based verification page and PDF certificates for convenience.
Conclusion: Set It and Forget It
Timestamp GIT turns cryptographic prior art protection from a manual chore into an automatic background process. Install the GitHub App once, select your repositories, and every future commit flows through the same pipeline: hash detection, nightly batching, Merkle tree construction, Bitcoin anchoring, and proof delivery.
The security model is intentionally zero-knowledge. Your source code is never read or stored. Standard Mode only processes commit hashes, and Enterprise ZK Mode keeps even those hashes under your control until you push them to the API.
Pricing covers the common cases: Open Source is free for public repositories, Pro Agency costs $49/month for private repositories, and Enterprise ZK costs $199/month with GitHub Actions support. For air-gapped or self-managed environments, a Docker self-hosted license is also available.
If you are still manually creating timestamps for individual commits, the faster path is to install the Timestamp GIT GitHub App or request a Docker self-hosted license for maximum control.
Related posts
- Timestamp GIT vs Manual OpenTimestamps: Which Is Better?
- How to Prove Prior Art for Software: A Developer’s Guide
- How to Protect Your Software from Patent Trolls
