Timestamp GIT

← All posts

2026-11-07

使用 GitHub App 自动化 Git 提交时间戳

使用 GitHub App 自动化 Git 提交时间戳
timestamp git blockchain proof

使用 GitHub App 自动化 Git 提交时间戳

你已经认定你的提交值得拥有加密的存在性证明。很好。现在运营层面唯一重要的问题是:这个证明是在你想到它的时候才发生,还是每天晚上不管有没有人想到它都会发生?

任何时间戳流程的第一个版本都是手动操作。团队里有人写了个脚本,在发布前运行一次,把文件保存到某个地方,然后觉得挺有保障。六周后,这个人去度假了,脚本在一台被重装过系统的笔记本电脑上,而发布分支根本没有被盖过时间戳。更糟的是,没人注意到——因为一个时间戳覆盖不完整的仓库,在审计员问起某个具体日期之前,看起来和完全覆盖的仓库一模一样。

本文讲的是自动化路径:一次安装,无需每次提交的仪式,开发者机器上无需任何工具。我们将涵盖一次性设置、从 git push 到比特币区块之间实际发生的过程、如何监控这条流水线,以及自动化可能悄悄出错的地方。

手动时间戳的陷阱(以及为什么自动化胜出)

手动时间戳有一个可预测的失败模式:它随纪律性而扩展,而纪律性无法跨团队、跨仓库、跨时区扩展。

具体来说,手动方式意味着为你关心的每一次提交运行一个 CLI 步骤或定制脚本——或者更糟,手动拼装底层的比特币交易数据。那是困难的方式,而且它在三个方面会出问题:

  • 它是逐提交的。 每周一百次提交就变成一百次跳过该步骤的机会。
  • 它依赖环境。 脚本存在于某人的机器上,而不是仓库的历史里。新员工没有它;CI 默认也没有它。
  • 它作为策略无法验证。 合规部门无法判断某个时间戳缺失是因为那天什么都没发生,还是因为有人忘了。

对开发者来说,要求很简单:我的工作流程什么都不变。 对合规部门来说,要求同样简单:每个受监控仓库中的每一次提交都被覆盖,而且我能证明这一点。

这就是为什么选择 GitHub App 作为自动化界面,而不是 CLI。Timestamp GIT 的 GitHub App 在组织级别安装一次,然后监视你选定仓库的每一次提交,并在夜间将它们锚定到比特币——在所有人都回家很久之后。

一次性设置:安装 GitHub App,然后忘掉它

设置只需一遍,由管理员完成,而不是每个开发者。

  1. 安装 App 到你的 GitHub 组织或个人账户。
  2. 选择要监控的仓库。 没有逐仓库的配置文件,没有 CI 变更,也没有开发者机器上的安装。
  3. 授予权限。 GitHub 的权限系统不提供"仅提交哈希"的范围,所以 App 需要对源仓库的只读访问权限,以及对写入证明的目标仓库的读写访问权限。那个读写目标可以是同一仓库中专门的 timestamps 分支,也可以是一个单独的影子仓库——由你决定。
  4. 完成。 从这里开始,检测通过 GitHub webhook 运行,你的团队不需要做任何其他事情。

如果你想要更严格的隔离模型,Enterprise ZK 模式将 webhook 检测替换为一个 12 行的 GitHub Action,在你自己的基础设施上执行。该 Action 只将提交哈希推送到 Timestamp GIT API。在此模式下,服务完全不需要对源仓库的读访问权限——只需要对接收证明的目标仓库的读写访问权限。当然,你需要安装该 Action 本身。

在气隙或高安全环境中自托管

为了最大程度的控制,Timestamp GIT 以 Docker 镜像形式提供,采用自托管许可证。一个快速开始的 Docker Compose 配置如下所示:

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

应用启动后可在 http://localhost:8080 访问。首次启动时,设置向导会引导你连接 GitHub App 并配置实例。评估运行在限时演示许可证上,通过 Docker License 页面 申请,需提供你的姓名、公司、电子邮件,以及可选的电话号码。

自动化流水线内部:从提交到比特币锚定

一旦安装,流水线在设计上就平淡无奇。这正是重点——它应该是无聊的。

1. 提交检测。 GitHub App 通过 webhook 捕获新提交。在 Enterprise ZK 模式下,你的 GitHub Action 改为将哈希推送到 API。无论哪种方式,只有提交哈希在移动。

2. 哈希队列。 哈希落入内存键值存储,等待下一批次。这是有意为之:将数百次提交批量合并到一个比特币锚定中,正是让整个方案足够便宜、可以在你拥有的每个仓库上运行的原因。

3. 午夜 cron 工作进程。 每晚一个工作进程将所有待处理的哈希分组,写入逐仓库的清单文件(.txt),原生构建 Merkle 树,针对公共 OTS 日历创建 OpenTimestamps 证明,并将 Merkle 根锚定到比特币区块链中。

4. 证明交付。 清单和 .ots 收据文件被推回你的仓库——推入专门的 timestamps 分支或影子仓库。比特币确认通常需要大约 3 小时,所以证明写入通常在批次开始几小时后完成。

ZK 模式发起的 API 调用如下所示({hash} 段是来自签名 URL 的 HMAC 值,不是提交哈希):

curl -X POST \
  "https://timestampgit.dev/api/timestamp/acme/payments-api/proofs/<hmac>/<commit-sha>/<commit-id>"

注意该载荷中没有什么:没有 diff,没有文件内容,没有分支名,除了提交 ID 所暗示的之外没有作者身份。这里的零知识安全不是营销口号——服务从不查看、复制或存储你的源代码,只处理 Git 哈希。

还要注意你的开发者不需要什么:任何命令、任何钩子、任何标志。他们照常推送。证明第二天早上出现。

监控与故障处理:保持你的证明可靠

你无法观察的自动化只是多了几步的希望。有三个可见性层级,你应该全部使用。

公开状态仪表板

每个受监控的仓库都有一个状态页面,位于 https://timestampgit.dev/status/{user}/{repo},显示证明的持久性(覆盖范围可追溯到多久以前)、最早的锚定日期、每日规律性、比特币区块和交易数据,以及日历热力图。热力图是发现缺口最快的方式:单独一个缺失的日子会立刻凸显出来。

README 徽章

从 https://timestampgit.dev/connected/{user}/{repo} 获取嵌入组件,它会给你一个实时的 Shields.io 预览以及可复制粘贴的 Markdown。徽章链接到一个任何人都可以查看的公开验证页面——当你希望客户或审计员在不创建账户的情况下确认覆盖情况时很有用。

# Returns badge URLs and ready-to-paste markdown snippets
curl https://timestampgit.dev/api/badgeLink/acme/payments-api

私有仓库也得到处理:它们的 URL 携带一个特定于服务器实例的加密 HMAC,因此只有授权用户才能读取状态。

程序化监控与审计导出

公开状态端点设计为可由你自己的工具轮询:

# 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

对于合规报告,使用 GET /api/audit/{user}/{repo} 拉取完整的审计账本 CSV,使用 GET /api/report/{user}/{repo}/{date} 获取每日 PDF 证书。

当一次运行失败时

如果夜间运行延迟或失败,待处理的哈希会留在队列中并滚入下一批次——提交不会被丢弃。在实践中,问题的症状是状态热力图上的平坦段,而不是数据丢失。在两个地方关注它:自托管实例用 docker compose logs -f timestampgit,SaaS 则看仪表板。

自动化提交时间戳的最佳实践

自动化消除了逐提交的成本,所以正确的默认值发生了变化:覆盖范围应该广泛,而不是精选的。

  • 监控每一个包含知识产权的仓库。 挑选"重要"仓库是一个伪装成自动化的手动决策——而你跳过的那个仓库总是最终证明重要的那个。另一个仓库的边际成本只是现有批次中的一个夜间哈希。
  • 对敏感代码库使用 Enterprise ZK 模式。 如果你的策略规定提交哈希本身不应经过第三方,GitHub Action 路线将除哈希之外的一切保持在你的边界内。对于完全隔离的环境,Docker 自托管许可证覆盖了同样的范围。
  • 按计划导出审计账本。 与法律文件放在同一文件夹中的 CSV 胜过你在纠纷期间会忘记的仪表板登录。
  • 在受监控的分支上尽早且频繁地提交。 许多小提交给你一条更密集的证明轨迹,其日期比发布时的一次大压缩更有说服力。
  • 避免在你依赖其作为在先技术的分支上重写历史。 强制推送会创建新的哈希;旧的哈希仍然被锚定,但"这段代码"和"这个证明"之间的映射变得更难向律师解释。如果你必须重写,先给重写前的状态打标签。
  • 将证明分支与源分支分开。 timestamps 分支或影子仓库是生成的输出——将其视为只读可避免意外合并到 main。

需要记住的一个边界:批处理加上大约 3 小时的比特币确认意味着下午 5 点做的提交到 5:05 是无法证明的。如果你需要今天的证明,请围绕夜间窗口规划,而不是期望即时结算。

常见问题

开发者需要运行任何命令或安装工具来为提交打时间戳吗?

不需要。一旦安装了 GitHub App,对受监控仓库的每一次提交都会被自动检测并每晚锚定到比特币。开发者继续照常使用 Git——没有 CLI,没有手动步骤。

提交后多久可以获得时间戳证明?

提交每晚批量处理并锚定一次。批次提交后,比特币确认通常需要大约 3 小时,所以证明通常在第二天早上可用。

我可以在不依赖 Timestamp GIT 的情况下验证时间戳吗?

可以。.ots 收据文件和 Merkle 证明是供应商无关的——SHA-256 加上比特币区块数据,没有专有格式。你可以下载它们,并使用标准 OpenTimestamps 工具对照比特币区块链进行检查,或者使用浏览器内验证页面,它在你的浏览器中本地完成所有计算。那个本地验证值得单独阅读:参见如何在浏览器中验证比特币时间戳证明。

如果我的仓库是私有的或包含敏感代码怎么办?

Timestamp GIT 从不读取或存储你的源代码——只处理提交哈希。对于更严格的隔离,Enterprise ZK 模式有一个 GitHub Action,只从你自己的基础设施推送哈希,或者你可以用 Docker 自托管。如果你在权衡与其他方法的取舍,Timestamp GIT 替代方案:首先比较什么涵盖了比较维度。

如果我使用多个 GitHub 组织怎么办?

在每个组织上安装 App,并监控你需要的仓库。你的仪表板将所有受监控的仓库聚合在一个地方。

结论

时间戳的价值与其需要的关注程度成反比。你手动生成的证明是为那些你记得的提交而存在的证明——在审计中,这读起来是一个不一致的流程,而不是一个受保护的流程。

安装 GitHub App 只需一次管理员会话。之后,对受监控仓库的每一次提交都会在你睡觉时被哈希、批处理、Merkle 根化并锚定到比特币中,带有用于公开可信度的徽章、用于合规的 CSV 账本,以及比任何供应商都长寿的 .ots 收据。开发者什么都不用改。

准备好停止手动操作了吗?为你的组织安装 GitHub App——公共仓库免费,私有仓库和仅哈希工作流提供 Pro Agency 和 Enterprise ZK 层级。

相关文章

EU label: AI-generated content