为每次 GitHub 提交自动添加比特币时间戳
你已经认定自己的提交值得拥有一份密码学存在性证明。很好。接下来是无聊的部分:明天再做一遍,后天再做一遍,团队接触的每个仓库都要做一遍。
大多数时间戳实践就是在这里悄无声息地死掉的。不是因为想法不对,而是因为手动操作——批量收集提交哈希、提交给日历服务、盯着证明文件、再把它提交回去——撑不过一个真实的冲刺周期。如果你想为 GitHub 仓库自动化区块链时间戳,时间戳必须是 git push 的副作用,而不是某个人记得在周五去做的任务。
本文端到端地走一遍自动化路径:一次安装、一条你永远不用碰的夜间流水线,以及能告诉你证明是否真的落到了比特币上的监控。
为什么手动打时间戳无法扩展
给提交打时间戳的笨办法就是每次都手动做。你需要负责:
- 判断哪些提交值得打戳(所有提交都值得,这正是问题所在)。
- 自己批量收集哈希,以免为每个提交创建一笔比特币交易。
- 提交到公共日历,并跟踪待处理的证明直到确认。
- 把生成的证明文件存到某个持久的地方,并与正确的提交关联。
- 明天再来一遍,每次强制推送、热修复和合并列车之后也要再来一遍。
即使写成脚本,这也是一份兼职工作。总得有人负责脚本、cron 运行器、存储位置,以及"上周的证明为什么不见了"这类事故。而这个人一换团队,流水线就烂掉了。
原始的 OpenTimestamps 协议确实很优雅——你可以在 OpenTimestamps 替代方案:为每次提交提供托管的 GitHub App 中了解它的工作原理。本文讲的是另一个问题:让它无人值守、永久运行下去。
目标是设置后即忘:被监控仓库的每次提交每晚都会被锚定,无需开发者干预,也无需在任何人的笔记本电脑上安装任何东西。
一次性设置:安装 GitHub App
Timestamp GIT 是一项围绕 GitHub App 构建的托管服务。设置只需几分钟,每个账户或组织只需做一次。
1. 安装应用。 在 Timestamp GIT 仪表盘中,将 GitHub App 安装到你的个人账户或组织上。
2. 选择仓库。 选择所有仓库或特定的子集。之后可以调整选择,无需重新安装。
3. 确认权限。 权限模型被刻意设计得很窄:
| 访问权限 | 范围 | 原因 |
|---|---|---|
| 只读 | 源仓库 | GitHub 权限系统没有"仅提交哈希"的范围,因此应用需要读权限才能看到 HEAD 提交哈希 |
| 读写 | 目标仓库 | 证明会以清单文件和 .ots 收据的形式写回专用分支或影子仓库 |
4. 走开。 没有 YAML 要添加,没有密钥要轮换,没有 CLI 要安装。你的开发者照常提交;应用在后台响应 webhook。
如果你的仓库是公开的,开源层级开箱即用即可覆盖。私有仓库从 Pro Agency 层级起步——定价详解介绍了哪个层级适合哪种团队形态。
更严格的替代方案:Enterprise ZK 模式
标准模式需要对源仓库的读访问权限。如果你的政策禁止这样做——或者你只是不想让任何第三方能读取你的代码——Enterprise ZK 模式会反转方向。不是拉取,而是由你这边推送:一个 12 行的 GitHub Action 在你自己的基础设施上运行,只把提交哈希发送到 Timestamp GIT API。你的源代码永远不会离开你的环境,服务也完全不需要对源仓库的读访问权限。只有目标仓库(写入证明的地方)需要写访问权限。
自动化流水线:从提交到比特币
以下是设置之后发生的事情,你什么都不用做。
1. 提交检测。 新提交通过 GitHub App 的 webhook(标准模式)或通过你的 GitHub Action 推送的哈希(Enterprise ZK 模式)到达。
2. 哈希队列。 提交哈希进入内存键值存储,等待夜间批次。注意那个存储里没有什么:你的代码。只有哈希。
3. 午夜 cron 工作进程。 每晚一次,一个工作进程会:
- 将所有待处理的哈希分组。
- 构建按仓库划分的清单(
.txt)。 - 在批次上原生构建 Merkle 树。
- 针对公共 OTS 日历生成 OpenTimestamps 证明。
- 将 Merkle 根锚定到比特币区块链。
4. 证明交付。 清单和 .ots 收据文件会被推回你的仓库——要么放在代码旁边的专用 timestamps 分支上,要么放在单独的影子仓库中。
时间预期。 比特币不会立即确认。锚定交易通常在大约三小时内确认,因此预计证明会在 UTC 午夜后几小时出现。如果你在 UTC 00:05 检查却什么也没看到,那并没有出问题。
用于自定义工作流的 API 接口
流水线自行运行,但 API 让你可以把证明数据接入自己的工具。所有端点按注明进行身份验证。
# Last anchored Bitcoin block for a repository (public)
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api
# Total stamped commits (public)
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api
# Combined summary, handy for Shields.io
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api
# Full Merkle chain data for a specific day, for local verification
curl -s https://timestampgit.dev/api/verify/acme/payments-api/2026-10-25
# Audit ledger as CSV
curl -s -o audit.csv https://timestampgit.dev/api/audit/acme/payments-api
# PDF certificate for one date
curl -s -o certificate.pdf https://timestampgit.dev/api/report/acme/payments-api/2026-10-25
Enterprise ZK 安装还会使用 HMAC 认证的提交端点,其中 {hash} 是你的 Action 请求的签名 URL 所返回的 HMAC 值:
curl -X POST \
"https://timestampgit.dev/api/timestamp/acme/payments-api/timestamps/<hmac>/<commitId>"
这就是全部的集成接口。没有"启动批次"的调用需要调度——批处理是服务的职责。
监控与故障处理
你不监控的自动化只是乐观主义。Timestamp GIT 提供三种独立方式来确认流水线健康。
公共状态仪表盘
每个仓库都有一个公共仪表盘,位于 /status/{user}/{repo},显示:
- 证明的持久性和最早锚定日期——你的证明链能追溯到多久以前。
- 每日规律性,以日历热力图呈现,这样漏掉的夜晚一目了然。
- 每个锚定的比特币区块和交易数据。
验证徽章
在 README 中嵌入 Shields.io 徽章,让证明公开可见:

/connected/{user}/{repo} 页面提供一个徽章嵌入小部件,带实时预览,包括 markdown 片段。对于私有仓库,状态 URL 携带特定于服务器实例的加密 HMAC——状态只对拥有签名链接的人可见。
自托管健康检查
由于状态端点是纯 JSON,你自己 CI 中的一个小脚本就能在审计员之前发现停滞的流水线:
import requests
BASE = "https://timestampgit.dev"
USER, REPO = "acme", "payments-api"
r = requests.get(f"{BASE}/api/statusLast/{USER}/{REPO}", timeout=15)
r.raise_for_status()
last = r.json() # last anchored Bitcoin block info for this repository
print(last)
# Compare against yesterday's stored value in your own job to detect a stalled batch.
如果夜间批次没有完成怎么办?可观察的信号在所有情况下都一样:热力图显示空缺,最后锚定的区块停止推进。由于锚定按天分批,漏掉一次运行会在 24 小时内被发现,而不是等到审计时——而且由于哈希队列和清单按日期键控,重新运行会产生一个不同的、带日期的证明,而不是模糊不清的证明。先检查仪表盘,再检查仓库的 timestamps 分支,确认清单和收据是否已写入。
审计追踪
对于合规审查,有两个产物承担主要工作:
GET /api/audit/{user}/{repo}—— 完整账本,CSV 格式。GET /api/report/{user}/{repo}/{date}—— 单个日期的 PDF 证书。
当有人想验证数学而不是信任 PDF 时,/verification/{user}/{repo}/{date} 页面会逐步展示多级 Merkle 链。所有计算都在浏览器本地进行——你验证的内容不会发送到服务器。
自动化时间戳的最佳实践
流水线运行起来后,几个习惯能让证据保持有用:
- 尽早提交、频繁提交。 每次提交都是现有技术的一个数据点。在提交申请前把一个月的工作压缩成一个提交,你只会得到一个锚定,而不是四十个。
- 把证明放在自己的分支上。 自动化的
timestamps分支是机器写入的;让它与功能分支分开,可以保持git log可读,并避免合并噪音。 - 定期验证,而不只是在争议时验证。 每季度通过网页验证器抽查一个最近的日期。在诉讼期间发现验证链断裂,那可不是发现它的好时机。
- 随发布一起交付证明。 将发布日期的清单和收据附加到发布产物中,并在法律文档中引用该日期。
- 给任何可能申请专利的东西打标签。 提交会被自动捕获;当你开始讨论一个可专利的想法时,确保工作已提交,而不是躺在本地分支里。
使用 Docker 自托管自动化
托管是默认选项,但有些环境无法使用它:气隙网络、严格的数据驻留要求,或禁止任何外部服务接触仓库元数据的内部政策。
对于这些情况,Timestamp GIT 以 Docker 镜像形式提供。自动化完全相同——同样的夜间批处理、Merkle 树构建和比特币锚定,只是运行在你的基础设施中。
一个快速入门的 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 许可证页面 申请限时演示许可证——需要姓名、公司、电子邮件和可选的电话号码。限时演示许可证文件可供下载,你在本地部署设置阶段上传它。
常见问题
我需要开发者的机器上运行任何命令或安装工具吗? 不需要。Timestamp GIT 完全通过 GitHub App 工作。安装后,被监控仓库的每次提交都会每晚自动打时间戳。没有 CLI 工具,没有 OpenTimestamps 命令,没有手动步骤。
提交打上时间戳需要多长时间? 提交每晚批量处理并锚定一次。比特币交易通常在大约 3 小时内确认,因此证明通常会在 UTC 午夜后几小时可用。
我可以在不信任 Timestamp GIT 的情况下独立验证时间戳吗?
可以。.ots 收据文件可以使用标准 OpenTimestamps 工具对照比特币区块链进行验证。证明仅依赖 SHA-256 和比特币区块数据,因此即使我们的服务消失,你也可以离线验证。
如果我需要完全保密源代码怎么办? 使用 Enterprise ZK 模式:你基础设施上的 GitHub Action 只将提交哈希推送到我们的 API。我们永远没有对你源代码的读访问权限。或者,使用 Docker 自托管以获得完全控制。
时间戳流水线会接触我的源代码吗? 不会。标准模式读取提交哈希;Enterprise ZK 模式根本看不到你的仓库内容。服务只处理 SHA-256 哈希和比特币区块数据。
你无需操心的时间戳
密码学现有技术的价值来自覆盖范围,而不是单个令人印象深刻的证明。一个英勇的下午打出的一个时间戳几乎证明不了什么;十八个月的夜间锚定才能证明一条时间线。这是一个量的问题,而量的问题靠自动化解决。
这就是 Timestamp GIT 的全部卖点:安装一次 GitHub App,选择你的仓库,让夜间任务完成其余工作。证明落在 timestamps 分支上,徽章落在你的 README 中,审计 CSV 在法律部门需要时就在那里。如果你需要隔离,Enterprise ZK 模式或 Docker 可以让你在不放弃自动化的情况下实现。
安装应用,推送一个提交,明天早上检查仪表盘。
相关文章