自动每晚将 Git 提交锚定到比特币,零手动步骤
团队为提交“打时间戳”最常见的方式,是靠人记得去做。
有人完成了一个功能,想起这个提交应该被锚定,于是手动运行 OpenTimestamps 工作流——用最麻烦的方式——然后把收据存到某个地方。两周后,没人记得那个周二的收据是否还存在。另一位开发者加入进来,不知道这套仪式,于是六个月的提交都没有被打戳。
这就是手动时间戳的陷阱:证明覆盖率取决于记忆。在演示中它运行良好,但在一个团队、一个冲刺节奏和一年的员工流动中就会崩溃。自动每晚将 Git 提交锚定到比特币翻转了这个问题:锚定不再是一个人执行的任务,而成为你仓库的一种属性。你安装一次 GitHub App,每个提交都会在你睡觉时被批量处理并锚定。
本文端到端地介绍这条自动化路径——设置、流水线、监控、自托管——写给那些关心证明能否经受审计的开发者和合规人员,而不是关心照看 cron 任务的人。
手动时间戳的陷阱(以及自动化如何消除它)
手动为提交打时间戳有三种失败模式,而这三者都是结构性的,而非个人问题:
- 依赖记忆。 必须有人记得在正确的时刻运行工具,最好是在工作公开之前。对于在先技术目的而言,晚了就等于从未做过。
- 静默失败。 当手动运行失败时——网络抖动、日历过期、目录错误——不会有任何崩溃。你只是留下了一个覆盖缺口,而你要到一年后、在你需要这份证明的那场纠纷中才会发现它。
- 收据散落。 收据最终散落在笔记本电脑、Slack 线程、无人负责的共享驱动器里。找不到的证明就等于没有证明。
这些都无法扩展。一个独立开发者也许能让这套仪式维持几个月。一个十人团队则不会,而一家在数十个仓库中处理客户工作的代理机构更是毫无机会。每一个错过的夜晚都是记录中一个永久的空洞,因为你无法追溯锚定一个从未被捕获的哈希。
Timestamp GIT 是零配置的托管替代方案:一个 GitHub App,自动捕获提交哈希,将它们批量处理,并每晚通过 OpenTimestamps 协议锚定到比特币区块链中。无需 CLI 工具,无需手动收据,开发者机器上无需安装任何东西。你获得了密码学属性——一个不可变、可独立验证的日期——而无需自己运行底层协议。
本博客另有两篇更深入的探讨:如何验证 Git 仓库的比特币时间戳 涵盖验证方面,用于专利纠纷的 Git 提交时间戳证明 涵盖法律框架。本文则专注于自动化本身。
一次性设置:安装 GitHub App 然后忘掉它
设置是一个单一操作,每个仓库执行一次,或每个组织执行一次。
- 在仓库上(或在整个组织上,这样新仓库默认就被覆盖)安装 Timestamp GIT GitHub App。
- 选择存放你代码的源仓库。
- 选择证明将被写入的目标仓库——可以是同一仓库上的专用分支,也可以是一个单独的影子仓库。
这就是全部配置。没有开发者机器要求:没有守护进程,没有每位工程师都必须安装的钩子,没有入职检查清单。新员工在第一次提交时就被覆盖,因为覆盖率是仓库的属性,而不是个人的属性。
权限模型。 标准模式需要对源仓库的只读访问,以及对目标仓库的读写访问。只读要求的存在是因为 GitHub 的权限系统不提供仅限提交哈希的范围——对源的读访问是让 App 能看到 HEAD 提交哈希的最低授权。它只会读取那个哈希。
如果连一个哈希都不应离开你的环境, 企业 ZK 模式用一段 12 行的 GitHub Action 取代 App 的轮询,该 Action 在你自己的基础设施上运行,只向 Timestamp GIT API 推送提交哈希。在该模式下,服务只需要对目标仓库的读写访问,完全不需要对源仓库的读访问——你改为安装该 Action。
无论哪种方式,保证都是一样的:我们永远不会看到、复制或存储你的实际源代码。只有哈希会参与其中。
自动化流水线内部:从提交到比特币锚定
一旦安装,流水线无需干预即可运行。以下是你的 git push 与一份不可变证明出现在你仓库之间所发生的事。
1. 提交检测。 在标准模式下,GitHub App 通过 webhook 检测新提交。在企业 ZK 模式下,你的 GitHub Action 将提交哈希推送到 API。两条路径产生相同的产物:一个提交哈希列表。
2. 哈希队列。 传入的哈希进入一个纯粹用于批量处理的内存键值存储。这是等候室——提交在这里累积,直到下一个批次窗口。
3. 午夜 cron 工作进程。 每晚,一个工作进程取出所有待处理的哈希并:
- 按仓库对它们分组,
- 为每个仓库写入一个清单文件(
.txt), - 在该批次上原生构建一棵 Merkle 树,
- 使用公共 OTS 日历创建 OpenTimestamps 证明,
- 将 Merkle 根锚定到比特币区块链中。
批量处理正是让这件事既便宜又持续的原因。无论你那天推送了一个提交还是四百个,成本和节奏都是一样的。
4. 证明交付。 清单和 .ots 收据文件被自动推送回你的仓库——推送到专用的 timestamps 分支或你的影子仓库中。
有一个值得提前规划的时间细节:在比特币区块链中确认需要几个小时,通常大约三个小时。所以今天推送的提交今晚排队,过夜锚定,证明文件在几小时后出现。你无需等待;你只需第二天早上在那里找到它们。
结果是,每天、每个仓库形成一条防篡改的链条:你的提交哈希 → 清单 → Merkle 树 → Merkle 根 → OpenTimestamps 证明 → 比特币区块。
监控与故障处理:保持链条不断裂
你不监控的自动化,只是手动陷阱一个更好看的版本。Timestamp GIT 公开了状态端点,这样你可以自己检查链条,无需登录仪表板:
# Last anchored Bitcoin block info for a repo
curl -s https://timestampgit.dev/api/statusLast/{user}/{repo}
# Total committed / stamped commit count
curl -s https://timestampgit.dev/api/statusCount/{user}/{repo}
# Combined summary, used for Shields.io badges
curl -s https://timestampgit.dev/api/statusSummary/{user}/{repo}
一个适合任何调度器的简单连续性检查:每天调用一次 statusLast,存储原始响应,如果它自昨天以来没有变化就发出警报。如果没有新的锚定落地,你就在同一周而不是同一个十年内发现了缺口。
如果你不想自己构建这个,位于 https://timestampgit.dev/status/{user}/{repo} 的公共状态仪表板会以可视化方式完成这项工作——证明寿命、最早锚定日期、每日规律性、每个锚定背后的比特币区块和交易数据,以及一张让错过的夜晚一目了然的日历热力图。在同一页面上,你可以下载审计 CSV 和 PDF 证书。
私有仓库保持私有。 私有仓库的状态 URL 带有一个特定于服务器实例的加密 HMAC,因此只有授权用户才能读取那些仓库的状态。这些证明在比特币意义上仍然是可公开验证的——哈希在链上——但周围的元数据并非一本公开的书。
验证徽章。 对于公共仓库,可嵌入的徽章直接在 README 中呈现你的验证状态,并带有一个任何人都可以点击的链接,在网站上验证时间戳。徽章让客户、收购方或对方律师无需你出示任何东西就能看到证明。
当 App 重新连接时。 如果一个仓库被断开并重新连接,连接页面会给你带有实时预览的徽章嵌入小部件,这样你可以重新验证链接是否完好。
可靠每晚锚定的最佳实践
- 每周让一个人看一眼热力图。 每晚自动化消除了日常任务,但没有消除责任。每周花五分钟看一眼状态仪表板,能捕捉到任何警报可能遗漏的东西。
- 对缺失发出警报,而不仅仅是对错误。 危险的状态是沉默。当锚定日期停止推进时发出警报。
- 使用专用的
timestamps分支或影子仓库。 将证明排除在你的默认分支之外意味着没有合并噪音,不会意外干扰 CI,并且审计追踪可供审查者浏览而无需克隆你的应用程序。 - 在买家会看的地方嵌入徽章。 在 README 中,靠近许可证头部。公开的存在证明是廉价的信誉。
- 按计划导出审计账本。 定期拉取 CSV 并将其与你的合规材料一起归档,并为每个发布里程碑生成一份 PDF 证书。合规团队想要一份带日期的文件;在他们开口之前就给他们一份。
- 把“谁能看到什么”的说明写下来。 记录你的模式——标准或企业 ZK——以及所授予的确切权限。当采购或法务询问时,你回答的是一个你已经回答过的问题。
面向气隙环境的自托管:Docker Compose 快速开始
如果你的约束排除了托管服务——受监管环境、气隙网络、严格的数据驻留规则——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 许可证页面 提交请求表单,附上你的姓名、公司、电子邮件和可选的电话号码,你就可以下载一个演示许可证文件来开始使用。
自托管为你提供最大的安全性和控制力,同时具有相同的每晚批量处理和锚定行为——Merkle 树、OTS 证明,以及写回你仓库的 .ots 文件。
常见问题
我需要在我的机器上运行任何命令或安装工具吗? 不需要。Timestamp GIT 是一项托管服务:你安装一次 GitHub App,每个提交都会每晚自动锚定。开发者机器上不安装任何东西。
一个提交被锚定到比特币需要多长时间?
每晚的 cron 工作进程会批量处理提交,并通过 OpenTimestamps 将 Merkle 根锚定到比特币中。确认通常需要大约 3 小时,之后 .ots 证明文件会被推送回你的仓库。
我可以独立验证时间戳吗?
可以。你可以下载 .ots 文件,并使用标准的 OpenTimestamps 验证工具对照比特币区块链进行验证,或者使用位于 https://timestampgit.dev/verification/{user}/{repo}/{date} 的公共验证页面,该页面在你的浏览器中本地运行多级 Merkle 链检查的每一步——没有人会看到你验证的内容。
如果我需要让我的源代码完全保密怎么办? 使用企业 ZK 模式:你基础设施上的一个 GitHub Action 只将提交哈希推送到 Timestamp GIT API,因此你的源代码永远不会离开你的环境。或者,使用 Docker 自托管以获得完全控制。
锚定的好坏取决于其规律性
你做过一次的时间戳只证明关于一个时刻的一件事。每晚自动做一次的时间戳证明一个仓库在一条连续时间线上以特定状态存在过——而当有人在十八个月后质疑你时,经得起考验的正是这个版本。手动打戳无法产生那份记录,因为记录是由你没有错过的那些日子定义的。
Timestamp GIT 正是为此而构建:在你的仓库或组织上安装 GitHub App,选择证明落地的地方,让每晚的工作进程批量处理、构建 Merkle 树,并将你的提交哈希锚定到比特币中。用徽章、仪表板或 .ots 文件本身进行验证。如果你更愿意在自己的网络内运行它,Docker 自托管许可证可以满足你。
安装一次。然后就不再想它。