Timestamp GIT

← Tutti gli articoli

2026-10-22

Timestamping Git automatizzato: ancora i commit a Bitcoin

Timestamping Git automatizzato: ancora i commit a Bitcoin
timestamp git blockchain proof

自动化 Git 时间戳:将提交锚定到比特币

如果你的在先技术保护依赖于有人在每次提交后记得运行某个工具,那你拥有的不是在先技术保护——而是一个习惯。而习惯会在审计前一周、发布冲刺期间,或者那个“总是做这件事”的人转岗之后立刻崩塌。

手动打时间戳有一个可预见的失败循环。你提交,然后你记得去盖章。你把收据复制到一个不会丢失的地方。你明天再做一次,后天再做一次,对每一个重要的仓库都如此——而一旦你进入分支繁多的冲刺阶段,这个循环就会悄无声息地停止。一个仓库还能扩展。五个仓库、每个仓库三个贡献者就不行了。

本文要讲的是彻底消除这个循环:在比特币上进行自动化 Git 时间戳,其中唯一重复的动作就是你已经打算做的提交。

你可以用困难的方式来做这件事——自己运行 OpenTimestamps 工具并照看收据文件。Timestamp GIT 的存在就是为了让你不必如此。它是一个托管服务,将协议完全隐藏起来:安装一次 GitHub App,被监控仓库的每一次提交都会在每晚自动锚定到比特币中。无需 CLI 工具,无需协议命令,无需每日清单。安装步骤本身请参见 GitHub App 区块链时间戳设置:安装一次,永久打戳——本文关注的是安装之后发生的事情。

你可以消除的重复性手动任务

在决定采用自动化之前,值得明确指出究竟从你的每周工作中移除了什么:

  • 每次提交的仪式。 每次值得证明的提交之后都必须运行某些东西。这意味着每个提交、永远,都需要一个人参与其中。
  • 收据散落各处。 证明文件最终散落在个人文件夹、共享驱动器或 Slack 线程中。六个月后,没人能把收据对应到某个日期或某个仓库。
  • 覆盖范围衰减。 你保护了旗舰仓库。内部工具仓库、客户端库、商业秘密服务——没人给这些打戳,而这些在纠纷中往往才是关键。
  • 静默缺口。 漏掉一天是看不见的,直到你需要证明时才会发现——而那是发现时间线漏洞的最糟糕时机。

这里所说的“自动化”含义狭窄而具体。你在想要监控的仓库上安装一次 GitHub App。从那时起,每一次提交都会被检测、批处理,并在每晚锚定到比特币区块链中,无需开发者做任何操作。开发者完全按照今天的方式继续提交。他们的机器上无需安装任何东西,没有 pre-commit 钩子,没有需要学习的新工作流。

这就是一个流程和你的仓库的一个后台属性之间的区别。

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

Timestamp GIT 提供两种连接仓库的方式,两者都是一次性配置。

标准模式(GitHub App)。 在你想监控的仓库上安装 GitHub App。它会自动只读取每个被监控仓库的 HEAD 提交哈希。证明会被写入一个专用的 Git 分支——可以是与源仓库相同的仓库,也可以是一个单独的仓库。

权限模型值得直白地理解,因为它比人们预期的要少:

  • 对源仓库的只读访问。 GitHub 权限系统没有“仅提交哈希”的范围,因此只读是 App 为了看到 HEAD 哈希所能请求的最低权限。
  • 对目标仓库的读写访问,即清单和收据文件被推送到的位置。

企业 ZK 模式。 一个 12 行的 GitHub Action 在你自己的基础设施上运行,只将提交哈希推送到 Timestamp GIT API。该配置只需要对目标仓库的读写访问——不需要对源仓库的读访问,你的源代码永远不会离开你的环境。

无论你选择哪种模式,你的团队的开发者体验都是一样的:开发者机器上无需安装任何东西,任何人分支、提交或合并的方式都无需改变。

如果你需要自托管。 为了最高安全性或气隙环境,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 并配置你的实例。许可、演示许可证申请表单以及完整的自托管操作指南见 自托管 Git 时间戳:Docker 设置与许可证指南。

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

一旦连接,流水线就会在无人干预下运行。以下是实际的顺序。

1. 提交检测。 要么 GitHub App 通过 webhook 检测到新提交,要么——在企业 ZK 模式下——你的 GitHub Action 将提交哈希推送到 API。

2. 哈希队列。 提交哈希进入一个内存键值存储以进行批处理。不存储其他任何东西,因为没有发送其他任何东西。

3. 午夜 cron 工作进程。 每晚,一个工作进程会:

  • 将所有待处理的哈希分组
  • 创建按仓库划分的清单文件(.txt)
  • 原生构建 Merkle 树
  • 使用公共 OTS 日历创建 OpenTimestamps 证明
  • 将 Merkle 根锚定到比特币区块链中

4. 证明交付。 清单和 .ots 收据文件被推送回你的仓库中一个专用的时间戳分支或影子仓库。

整个流程如下所示:

commit ──▶ hash queue ──▶ midnight cron ──▶ Merkle root ──▶ Bitcoin block
                                                 │
                                                 └──▶ manifest.txt + .ots receipt
                                                              │
                                                              ▼
                                                  timestamps branch / shadow repo

在企业 ZK 模式下,你的 GitHub Action 与 ZK Commit API 通信,该 API 使用 API 为你的仓库返回的签名 URL 中的 HMAC 进行身份验证:

# The signed URL (and its HMAC) is returned by the API for your repo.
# {target} is the destination repo, {hash} is the HMAC from that URL.
curl -X POST \
  "https://timestampgit.dev/api/timestamp/acme/payments-api/timestamps/<hmac>/<commitHash>/<commitId>"

时间预期。 比特币确认需要几个小时——通常大约 3 小时——因此证明写入会在夜间运行后几小时完成,而不是在午夜整点。如果你在 00:05 检查你的时间戳分支却什么也没看到,那是预期行为,不是故障。

监控与故障处理

你无法观察的自动化与已经停止工作的自动化无法区分。Timestamp GIT 公开了状态端点,因此你无需登录即可观察流水线:

# Last anchored Bitcoin block
curl -s https://timestampgit.dev/api/statusLast/acme/payments-api

# Total committed / stamped commit count
curl -s https://timestampgit.dev/api/statusCount/acme/payments-api

# Combined summary (Shields.io friendly)
curl -s https://timestampgit.dev/api/statusSummary/acme/payments-api

徽章。 可嵌入的验证徽章可用于你的 README,因此任何浏览仓库的人都能看到锚定状态。任何人都可以点击徽章链接来验证时间戳——有一个专用的查看器和一个 PDF 报告。私有仓库也受支持:它们的状态 URL 会附加一个特定于服务器实例的加密 HMAC,因此只有授权用户才能看到状态。

仓库状态仪表板。 在 /status/{user}/{repo} 你可以获得证明寿命、最早锚定日期、每日规律性、比特币区块和交易数据,以及一个日历热力图——这是以可视化方式发现覆盖缺口的最快方法。

审计和报告端点。 当你需要证据而不是仪表板时:

# Full audit ledger as CSV
curl -sO https://timestampgit.dev/api/audit/acme/payments-api

# PDF certificate for one specific date
curl -sO https://timestampgit.dev/api/report/acme/payments-api/2026-10-21

当某一晚看起来缺失时,按以下顺序排查:

  1. 检查 statusLast 和 statusCount。如果最后一次锚定比预期晚了几个小时,确认可能仍在进行中。
  2. 确认 GitHub App 仍然拥有仓库访问权限。卸载的 App、被撤销的权限或重命名的仓库都会静默地停止检测。
  3. 在企业 ZK 模式下,检查你这边 Action 的运行历史——推送到 API 是唯一可能在本地断开的环节。
  4. 在比特币确认完成后再重新检查,然后再假设任何东西丢失了。

自动化时间戳的最佳实践

  • 监控每一个重要的仓库,而不仅仅是旗舰仓库。覆盖范围是自动化的全部价值所在;只保护一个仓库仍然会让你其余的工作暴露在外。
  • 保持提交有意义。 自动化会为你提交的内容打时间戳,因此提交卫生仍然塑造着你锚定历史所讲述的故事。一百个“wip”提交证明的东西比一个干净、描述性的历史要少。
  • 把徽章放进 README,并将审计 CSV 和按日期的 PDF 报告与你的知识产权记录放在一起。这些产物才是你交给审计师或对方律师的东西。
  • 在关键时刻独立验证。 下载 .ots 文件,并用标准 OpenTimestamps 工具对照比特币进行检查。该证明在设计上就是供应商无关的——它只使用 SHA-256 和比特币区块数据。分步操作指南见 如何在本地验证比特币时间戳证明。
  • 记住零知识保证。 只有提交哈希被打戳,源代码永远不会,因此跨每个仓库自动化完全不会扩大你的暴露面——无论你有一个仓库还是五十个,都是同一个哈希。

常见问题

自动化 Git 时间戳会读取或存储我的源代码吗?

不会。Timestamp GIT 只处理提交哈希。在标准模式下,GitHub App 读取 HEAD 提交哈希;在企业 ZK 模式下,你基础设施上的 GitHub Action 只将哈希推送到 API。在 ZK 模式下,你的源代码永远不会离开你的环境,也永远不会被该服务复制或存储。

我提交后多久比特币锚定会被确认?

提交由夜间 cron 工作进程批处理并锚定。比特币确认需要几个小时,通常大约 3 小时,因此 .ots 收据和清单文件会在夜间运行后几小时出现在你的时间戳分支或影子仓库中。

如果 Timestamp GIT 关闭了,我的证明会怎样?

证明仍然有效。它们仅通过 OpenTimestamps 协议依赖 SHA-256 和比特币区块数据,因此任何人都可以下载 .ots 文件,并使用标准 OpenTimestamps 工具对照比特币区块链独立验证它——没有专有技术,没有锁定。

我可以在私有仓库上使用自动化时间戳吗?

可以。私有仓库受支持,状态 URL 会附加一个特定于服务器实例的加密 HMAC,因此只有授权用户才能查看状态。一旦授予访问权限,公共验证徽章和状态仪表板的工作方式相同。

结论:设置一次,永久证明

这里的转变在努力上很小,在后果上很大。你不再维护一项每日杂务,而是开始拥有你的仓库的一个属性:每一次提交,都被锚定到比特币中,自动地,每晚,并附有一份你可以交给律师、审计师或法庭的收据。证明嵌入在比特币中,可直接用于法庭,任何人都可以在没有专有工具的情况下验证——而这一切都由后端的 Timestamp GIT 驱动,而不是由你的开发者驱动。

如果你的团队完全无法使用托管服务,Docker 自托管选项通过上面展示的 Compose 配置覆盖了最高安全性和气隙环境。

今天就在你的第一个仓库上安装 GitHub App,让流水线今晚运行起来。明天,检查 statusLast——你将拥有一个否则你可能会花一年时间试图记得去创建的锚定。

相关文章

EU label: AI-generated content