使用 GitHub App 自动化 Git 提交时间戳
你已决定让你的提交获得加密的存在性证明。很好。现在从运维角度唯一重要的问题是:这个证明是在你想到它的时候发生,还是每晚无论有没有人想到它都会发生?
任何时间戳流程的第一个版本都是手动的。团队里某个人写个脚本,在发布前运行一次,把文件保存在某处,然后感觉受到了合理保护。六周后,这个人去度假了,脚本在一台被重装系统的笔记本电脑上,发布分支根本没有被打上时间戳。更糟的是,没人注意到——因为一个只有部分时间戳覆盖的仓库,在审计员询问某个具体日期之前,看起来和完全覆盖的仓库一模一样。
本文讨论的是自动化路径:一次安装,无需每次提交的仪式,开发者机器上无需任何工具。我们将涵盖一次性设置、从 git push 到比特币区块之间实际发生什么、如何监控这条流水线,以及自动化可能在哪里悄悄出错。
手动时间戳的陷阱(以及为什么自动化胜出)
手动时间戳有一个可预测的失败模式:它随纪律性扩展,而纪律性无法跨团队、仓库和时区扩展。
具体来说,手动方式意味着为你关心的每一次提交运行一个 CLI 步骤或定制脚本——或者更糟,手工组装底层的比特币交易数据。那是困难的方式,并且会在三个方面出问题:
- 它是按提交进行的。 每周一百次提交就变成一百次跳过该步骤的机会。
- 它依赖环境。 脚本存在于某人的机器上,而不是仓库的历史中。新员工没有它;CI 默认也没有它。
- 它作为策略无法验证。 合规部门无法判断时间戳缺失是因为那天什么都没发生,还是因为有人忘了。
对开发者来说,要求很简单:我的工作流程没有任何变化。 对合规部门来说,要求同样简单:每个受监控仓库中的每次提交都被覆盖,而且我能证明这一点。
这就是为什么选择 GitHub App 作为自动化界面,而不是 CLI。Timestamp GIT 的 GitHub App 在组织级别安装一次,然后监视你选择的仓库中的每一次提交,并在夜间将它们锚定到比特币——在所有人都回家很久之后。
一次性设置:安装 GitHub App 然后忘掉它
设置是一次性完成的,由管理员而非每个开发者完成。
- 安装 App 到你的 GitHub 组织或个人账户。
- 选择要监控的仓库。 没有按仓库的配置文件,没有 CI 更改,也没有开发者机器安装。
- 授予权限。 GitHub 权限系统不提供“仅提交哈希”的范围,因此 App 需要对你源仓库的只读访问权限,以及对写入证明的目标仓库的读写访问权限。那个读写目标要么是同一仓库中专门的
timestamps分支,要么是一个单独的影子仓库——由你决定。 - 完成。 从这里开始,检测通过 GitHub webhooks 运行,你的团队不需要做任何其他事情。
如果你想要更严格的隔离模型,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 许可证页面 申请,提供你的姓名、公司、电子邮件,以及可选的电话号码。
自动化流水线内部:从提交到比特币锚定
一旦安装,流水线在设计上就平淡无奇。这正是重点——它应该是无聊的。
1. 提交检测。 GitHub App 通过 webhooks 捕获新提交。在 Enterprise ZK 模式下,你的 GitHub Action 改为将哈希推送到 API。无论哪种方式,只有提交哈希在移动。
2. 哈希队列。 哈希落入内存键值存储,等待下一批。这是有意为之:将数百次提交批处理到一个比特币锚定中,正是让整个事情足够便宜,可以在你拥有的每个仓库上运行的原因。
3. 午夜 cron worker。 每晚一个 worker 将所有待处理的哈希分组,写入每个仓库的清单文件(.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 层级。