为每次 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 可以让你在不放弃自动化的情况下实现。
安装应用,推送一次提交,明天早上检查仪表盘。
相关文章