← All posts
Install a GitHub App for Automatic Code Timestamping

Install a GitHub App for Automatic Code Timestamping

timestamp git blockchain proof

Install a GitHub App for Automatic Code Timestamping

You want to install a GitHub app for code timestamping so that every commit you make is automatically anchored to the Bitcoin blockchain—without maintaining scripts, running cron jobs, or touching OpenTimestamps yourself. That is exactly what Timestamp GIT does: install the GitHub App once, select which repositories to protect, and every commit is hashed, batched, and anchored to Bitcoin nightly. No manual steps after setup.

This guide is transactional. You are ready to implement, not just evaluate. By the end, you will have the Timestamp GIT GitHub App installed, your first repository connected, and a verification badge or audit trail in place.

You could run OpenTimestamps manually, craft Bitcoin transactions by hand, and babysit cron jobs—the hard way. Or you can install a managed GitHub App and let Timestamp GIT hide the entire protocol behind a zero-setup workflow. This article walks through the first path.

Prerequisites for Installing the Timestamp GIT GitHub App

Before you begin, make sure you have:

Step-by-Step: Install and Configure the GitHub App

Step 1: Log in to Timestamp GIT and open the GitHub App installation page

Sign in at timestampgit.dev. Once logged in, navigate to the repository setup page—usually Your Repositories in the dashboard. Click the option to install the GitHub App.

Step 2: Authorize Timestamp GIT on your GitHub account or organization

Click Install GitHub App. GitHub will prompt you to choose between your personal account and any organizations you administer. Select the account that owns the repositories you want to protect.

Step 3: Select repositories and set source permissions

Choose which repositories Timestamp GIT should monitor.

Step 4: Choose where timestamp proofs will be stored

Select the target repository. This can be the same repository as your source code or a separate shadow repository. Timestamp GIT will push manifest files and .ots receipts to a dedicated timestamps branch in the target repository.

For Standard Mode, the target repository needs read-write access. For Enterprise ZK Mode, you need read-write access to the target repository only.

Step 5: For Enterprise ZK Mode, add the GitHub Action workflow

If you chose Enterprise ZK Mode, the Timestamp GIT dashboard generates a 12-line YAML snippet for you. Copy it into a workflow file in your source repository, for example .github/workflows/timestampgit.yml.

A generated workflow looks similar to this (use the exact snippet from your dashboard):

# Enterprise ZK Mode workflow generated by Timestamp GIT.
# This runs on your infrastructure and sends only commit hashes.
name: timestamp-git-zk
on:
  push:
    branches: [main]
jobs:
  send-hash:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v4
      - name: Send commit hash to Timestamp GIT
        env:
          TIMESTAMPGIT_HMAC: ${{ secrets.TIMESTAMPGIT_HMAC }}
        run: |
          # The exact command is generated by Timestamp GIT.
          # It pushes the HEAD commit hash to the API endpoint.

The action pushes only the commit hash. Your source code never leaves your environment.

Step 6: Confirm the setup in the Timestamp GIT dashboard

Return to Timestamp GIT and confirm the installation. In Standard Mode, the GitHub App will begin detecting commits via GitHub webhooks automatically. In Enterprise ZK Mode, the Action will push commit hashes to the API on each push.

At this point you should see your repository listed in Your Repositories with a status showing that it is connected.

Step 7: Add a verification badge to your README

From the repository connected page (https://timestampgit.dev/connected/{user}/{repo}), copy the markdown snippet for a Shields.io badge. It looks like this, with your actual user and repo names:

[![Timestamp GIT](https://timestampgit.dev/api/badgeLink/your-user/your-repo)](https://timestampgit.dev/status/your-user/your-repo)

Paste it into your README.md. Public visitors can click the badge to view the public verification status for your repository.

How to Confirm Timestamping Works

After installation, wait for the nightly batch and Bitcoin confirmation. Here is how to verify that your first commits were anchored correctly.

  1. Check the repository status page. Open https://timestampgit.dev/status/{user}/{repo}. It shows the earliest anchor date, daily regularity, Bitcoin block and transaction data, and a calendar heatmap of stamped commits.

  2. Look for the timestamps branch. In your target repository, find the dedicated timestamps branch (or the shadow repository). It contains manifest files and .ots receipt files for each daily batch.

  3. Run local verification in the browser. Visit https://timestampgit.dev/verification/{user}/{repo}/{date}. The page performs a step-by-step Merkle chain verification locally in your browser—zero-knowledge, nobody sees what you verify. You do not need to install anything.

  4. Download compliance records. Use the audit CSV and PDF certificate endpoints. For example:

    • https://timestampgit.dev/api/audit/{user}/{repo} downloads the full audit ledger as CSV.
    • https://timestampgit.dev/api/report/{user}/{repo}/{date} downloads a PDF certificate for a specific day.

  5. Remember the timing. Commits are batched each night by a cron worker. The Merkle root is then anchored into a Bitcoin transaction. Bitcoin confirmation normally takes around 3 hours, so proofs are usually available the next day. If you do not see a proof immediately after a commit, that is expected.

Troubleshooting Common Installation Issues

Issue: No commits are being timestamped.
Check that the GitHub App has the correct permissions and that the repository is selected in the Timestamp GIT dashboard. In Standard Mode, the app needs read-only access to the source repository and read-write access to the target repository. In Enterprise ZK Mode, the GitHub Action must be installed in the source repository and configured to push to the API.

Issue: Proofs not appearing after a day.
Confirm that the nightly cron worker ran and that the Bitcoin transaction was confirmed. Bitcoin confirmation usually takes about 3 hours after the batch is processed. Check the repository status page for the last anchored block info. If it has been more than 24 hours, verify that the target repository has a timestamps branch and that the GitHub App still has write access.

Issue: Private repository status is not visible.
Private repository status pages and badges are protected with an encrypted HMAC token. Make sure you are using the authenticated URL that contains the HMAC value. Also confirm you are on a paid plan (Pro Agency or Enterprise ZK). The free Open Source plan does not cover private repositories.

Issue: Enterprise ZK Mode not pushing hashes.
Verify that the GitHub Action workflow file is present in .github/workflows/ and that the TIMESTAMPGIT_HMAC secret is set correctly in your repository settings. Check the workflow run logs in GitHub Actions to confirm the API endpoint is reachable and the action completed successfully.

Issue: Verification fails locally on the public verification page or with a downloaded .ots file.
Ensure you are using the correct .ots file for the specific date. Also confirm that your local OpenTimestamps tooling is up to date if you are verifying outside the browser. The verification page itself performs all computation locally and should work with any modern browser.

FAQ

Does the Timestamp GIT GitHub App have access to my source code?

In Standard mode, the GitHub App requires read-only access to the source repository because GitHub does not provide commit-hash-only permissions. However, Timestamp GIT only extracts the commit hash and never reads or stores your source code. In Enterprise ZK mode, the 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 the Bitcoin blockchain?

Commits are batched nightly. After the batch is processed, the Merkle root is anchored into a Bitcoin transaction. Bitcoin confirmation typically takes around 3 hours, so the proof is usually available the next day. You can monitor the status on your repository dashboard.

Can I use Timestamp GIT for private repositories?

Yes, private repositories are supported on the Pro Agency ($49/month) and Enterprise ZK ($199/month) plans. The free Open Source plan is limited to public repositories. Private repo status pages and badges are protected with an encrypted HMAC token.

What happens if Timestamp GIT goes out of business? Can I still verify my timestamps?

Your proofs are stored as .ots files in your repository and anchored in the Bitcoin blockchain. You can verify them independently using standard OpenTimestamps tools and Bitcoin block data. No proprietary technology is required, so your evidence remains valid even without Timestamp GIT.

Conclusion: Start Protecting Your Code Today

Installing the Timestamp GIT GitHub App takes a few minutes. After that, every commit to a monitored repository is fingerprinted, batched, and anchored into the Bitcoin blockchain automatically. You get court-ready evidence, vendor-independent proofs, and zero ongoing effort.

If you need maximum security in an air-gapped or self-hosted environment, Timestamp GIT is also available as a Docker image with a time-limited demo license. But for most teams, the managed GitHub App is the fastest path to cryptographic prior art.

Start at Timestamp GIT, sign up, install the GitHub App, and connect your first repository today.

Published on Timestamp GIT · Timestamp GIT
EU label: AI-generated content