安装 GitHub 应用以实现代码自动时间戳

安装 GitHub App 以实现自动代码时间戳

你想安装一个用于代码时间戳的 GitHub App，让你每一次提交都自动锚定到比特币区块链——无需维护脚本、运行 cron 任务，或自己操作 OpenTimestamps。这正是 Timestamp GIT 所做的：安装一次 GitHub App，选择要保护的仓库，之后每一次提交都会被哈希、批量处理，并每晚锚定到比特币。设置完成后无需任何手动步骤。

本指南是实操性的。你已经准备好实施，而不仅仅是评估。到最后，你将完成 Timestamp GIT GitHub App 的安装，连接你的第一个仓库，并拥有验证徽章或审计追踪。

你可以手动运行 OpenTimestamps、手工构建比特币交易、照看 cron 任务——这是困难的方式。或者你可以安装一个托管式 GitHub App，让 Timestamp GIT 将整个协议隐藏在零配置的工作流背后。本文介绍的是第一条路径。

安装 Timestamp GIT GitHub App 的前提条件

在开始之前，请确保你具备：

• GitHub 管理员权限，针对你想要保护的仓库或组织。你需要权限来安装 GitHub App 并授予仓库访问权。
• 一个 Timestamp GIT 账户，在 timestampgit.dev 注册。使用你的 GitHub 身份登录。
• 对两种部署模式的理解：
  • 标准模式（GitHub App）：App 自动读取被监控仓库的 HEAD 提交哈希。它需要对源仓库的只读访问权限，因为 GitHub 不提供仅提交哈希的权限。它还需要对存储证明的目标仓库的读写访问权限。
  • 企业 ZK 模式（GitHub Action）：一个 12 行的 GitHub Action 在你自己的基础设施上运行，仅将提交哈希推送到 Timestamp GIT API。App 完全无法访问你的源仓库。你只需要对目标仓库的读写访问权限。
• 如果你为私有仓库打时间戳，需要一个付费计划。免费的 Open Source 计划覆盖公共仓库。私有仓库需要 Pro Agency（$49/月）或 Enterprise ZK（$199/月）。私有状态页面和徽章使用加密的 HMAC 令牌进行保护。
• 无需本地工具或 CLI 实用程序。一切都通过 Timestamp GIT Web 应用和 GitHub App 管理。你不需要在开发机器上安装任何东西。

分步指南：安装和配置 GitHub App

第 1 步：登录 Timestamp GIT 并打开 GitHub App 安装页面

在 timestampgit.dev 登录。登录后，导航到仓库设置页面——通常是仪表板中的 Your Repositories。点击安装 GitHub App 的选项。

第 2 步：在你的 GitHub 账户或组织上授权 Timestamp GIT

点击 Install GitHub App。GitHub 会提示你在个人账户和你管理的任何组织之间进行选择。选择拥有你要保护的仓库的账户。

第 3 步：选择仓库并设置源权限

选择 Timestamp GIT 应监控哪些仓库。

• 在标准模式下，授予对源仓库的只读访问权限。GitHub App 需要此权限，因为 GitHub 不提供仅提交哈希的权限。Timestamp GIT 只提取提交哈希，从不读取或存储你的源代码。
• 在企业 ZK 模式下，不要授予任何源仓库访问权限。GitHub Action 在你的 CI 流水线中运行，仅将哈希发送到 API，因此 App 永远不会接触你的代码。

第 4 步：选择时间戳证明的存储位置

选择目标仓库。它可以是与源代码相同的仓库，也可以是一个单独的影子仓库。Timestamp GIT 会将清单文件和 .ots 回执推送到目标仓库中一个专门的时间戳分支。

对于标准模式，目标仓库需要读写访问权限。对于企业 ZK 模式，你只需要对目标仓库的读写访问权限。

第 5 步：对于企业 ZK 模式，添加 GitHub Action 工作流

如果你选择了企业 ZK 模式，Timestamp GIT 仪表板会为你生成一个 12 行的 YAML 片段。将其复制到源仓库中的工作流文件中，例如 .github/workflows/timestampgit.yml。

生成的工作流类似于以下内容（请使用你仪表板中的确切片段）：

# 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.

该 Action 仅推送提交哈希。你的源代码永远不会离开你的环境。

第 6 步：在 Timestamp GIT 仪表板中确认设置

返回 Timestamp GIT 并确认安装。在标准模式下，GitHub App 将通过 GitHub webhook 自动开始检测提交。在企业 ZK 模式下，Action 将在每次推送时将提交哈希推送到 API。

此时，你应该能在 Your Repositories 中看到你的仓库，并显示已连接的状态。

第 7 步：将验证徽章添加到你的 README

从仓库连接页面（https://timestampgit.dev/connected/{user}/{repo}）复制 Shields.io 徽章的 Markdown 片段。它看起来像这样，使用你实际的用户名和仓库名：

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

将其粘贴到你的 README.md 中。公共访问者可以点击徽章查看你仓库的公开验证状态。

如何确认时间戳正常工作

安装后，等待每晚的批量处理和比特币确认。以下是如何验证你的第一批提交已正确锚定。

1. 查看仓库状态页面。 打开 https://timestampgit.dev/status/{user}/{repo}。它显示最早的锚定日期、每日规律性、比特币区块和交易数据，以及已打时间戳提交的日历热力图。

2. 查找时间戳分支。 在你的目标仓库中，找到专门的时间戳分支（或影子仓库）。它包含每个每日批次的清单文件和 .ots 回执文件。

3. 在浏览器中运行本地验证。 访问 https://timestampgit.dev/verification/{user}/{repo}/{date}。该页面在你的浏览器中本地执行逐步的 Merkle 链验证——零知识，没有人能看到你验证了什么。你不需要安装任何东西。

4. 下载合规记录。 使用审计 CSV 和 PDF 证书端点。例如：

   • https://timestampgit.dev/api/audit/{user}/{repo} 以 CSV 格式下载完整的审计台账。
   • https://timestampgit.dev/api/report/{user}/{repo}/{date} 下载特定日期的 PDF 证书。

5. 记住时间安排。 提交每晚由 cron 工作进程批量处理。然后 Merkle 根被锚定到一笔比特币交易中。比特币确认通常需要大约 3 小时，因此证明通常在第二天可用。如果你在提交后没有立即看到证明，这是正常的。

常见安装问题排查

问题：没有提交被打上时间戳。
检查 GitHub App 是否具有正确的权限，以及仓库是否已在 Timestamp GIT 仪表板中被选中。在标准模式下，App 需要对源仓库的只读访问权限和对目标仓库的读写访问权限。在企业 ZK 模式下，GitHub Action 必须安装在源仓库中，并配置为推送到 API。

问题：一天后证明仍未出现。
确认每晚的 cron 工作进程已运行，并且比特币交易已确认。比特币确认通常在批量处理完成后大约需要 3 小时。查看仓库状态页面上的最后锚定区块信息。如果已超过 24 小时，请验证目标仓库是否有时间戳分支，以及 GitHub App 是否仍然具有写入权限。

问题：私有仓库状态不可见。
私有仓库状态页面和徽章使用加密的 HMAC 令牌进行保护。确保你使用的是包含 HMAC 值的认证 URL。同时确认你使用的是付费计划（Pro Agency 或 Enterprise ZK）。免费的 Open Source 计划不覆盖私有仓库。

问题：企业 ZK 模式未推送哈希。
验证 GitHub Action 工作流文件是否存在于 .github/workflows/ 中，以及 TIMESTAMPGIT_HMAC 密钥是否已在你的仓库设置中正确配置。查看 GitHub Actions 中的工作流运行日志，确认 API 端点可达且 Action 已成功完成。

问题：在公共验证页面上或使用下载的 .ots 文件进行本地验证失败。
确保你使用的是特定日期的正确 .ots 文件。如果你在浏览器之外进行验证，还要确认你的本地 OpenTimestamps 工具是最新的。验证页面本身在本地执行所有计算，应该可以在任何现代浏览器中正常工作。

常见问题解答

Timestamp GIT GitHub App 能访问我的源代码吗？

在标准模式下，GitHub App 需要对源仓库的只读访问权限，因为 GitHub 不提供仅提交哈希的权限。然而，Timestamp GIT 只提取提交哈希，从不读取或存储你的源代码。在企业 ZK 模式下，GitHub Action 在你的基础设施上运行，仅将提交哈希推送到 API，因此 App 完全无法访问你的源仓库。

一个提交被时间戳到比特币区块链上需要多长时间？

提交每晚批量处理。批量处理完成后，Merkle 根被锚定到一笔比特币交易中。比特币确认通常需要大约 3 小时，因此证明通常在第二天可用。你可以在仓库仪表板上监控状态。

我可以为私有仓库使用 Timestamp GIT 吗？

可以，私有仓库在 Pro Agency（$49/月）和 Enterprise ZK（$199/月）计划上受支持。免费的 Open Source 计划仅限于公共仓库。私有仓库状态页面和徽章使用加密的 HMAC 令牌进行保护。

如果 Timestamp GIT 倒闭了怎么办？我还能验证我的时间戳吗？

你的证明以 .ots 文件的形式存储在你的仓库中，并锚定在比特币区块链中。你可以使用标准的 OpenTimestamps 工具和比特币区块数据独立验证它们。不需要专有技术，因此即使没有 Timestamp GIT，你的证据仍然有效。

结论：立即开始保护你的代码

安装 Timestamp GIT GitHub App 只需几分钟。之后，对被监控仓库的每一次提交都会被自动指纹化、批量处理，并锚定到比特币区块链中。你获得法庭级证据、供应商无关的证明，以及零持续维护成本。

如果你需要在气隙或自托管环境中获得最大安全性，Timestamp GIT 也可以作为 Docker 镜像提供，并附带限时演示许可证。但对于大多数团队来说，托管式 GitHub App 是获得加密在先技术的最快途径。

从 Timestamp GIT 开始，注册、安装 GitHub App，并在今天连接你的第一个仓库。