GitHub App 区块链时间戳设置:一次安装,永久时间戳
用一句话概括任务:在代码仓库上安装 Timestamp GIT GitHub App,这样你推送的每一次提交都会在每晚自动锚定到比特币区块链中——无需 CLI 工具,无需手动操作,也不会改变团队的工作方式。
你完全可以用更费劲的方式来做这件事:自己运行 OpenTimestamps 工具、管理日历、构建自己的 Merkle 批处理,还要盯着比特币确认。那简直是一份兼职工作。Timestamp GIT 的存在就是为了让它完全不需要你来操心。本指南将带你走完我们推荐的设置路径:一次安装、一次仓库选择、一个配置页面,然后就是一个你再也不用去想的夜间流水线。
到最后,你将获得每天为提交生成的 .ots 收据、README 中的验证徽章,以及一个公开状态仪表板,任何人——律师、审计员、客户——都无需账户即可查看。
你将设置什么(以及为什么这是一次性的工作)
确切的任务:将仓库连接到 GitHub App,使提交检测、哈希批处理、比特币锚定和证明交付全部自动完成,无需你介入。
你能从中获得什么:
- 每天一份不可篡改的
.ots收据——一份加密证明,证明一组特定的提交哈希在某个特定日期已经存在。 - 一个验证徽章,你可以放入 README,让证明状态公开可见。
- 一个状态仪表板,包含锚定日期、比特币区块和交易数据、每日规律性以及可下载的审计导出。
这种分工值得深入理解,因为它解释了为什么设置是一次性的工作:
- GitHub App 通过 webhook 检测提交。
- Timestamp GIT 在午夜对提交哈希进行批处理,构建 Merkle 树,并使用 OpenTimestamps 协议将 Merkle 根锚定到比特币中。
- 清单文件和
.ots收据文件被推送回你控制的专用timestamps分支或影子仓库。
存在两种部署模式,本指南遵循第一种:
- 标准模式(GitHub App)——完全托管,CI 中无需代码,仅读取受监控仓库的 HEAD 提交哈希。
- 企业 ZK 模式——在你自己的基础设施上运行一个小型 GitHub Action,仅将提交哈希推送到 Timestamp GIT API,并且只需要对目标证明仓库的读写权限。
如果你需要了解这一切为何重要的概念背景——专利流氓、员工纠纷、“洁净室”声明——请先阅读什么是加密现有技术?。本文假设你已经决定要使用它,现在想让它运行起来。
安装前的先决条件
- 一个对目标仓库(公开或私有)拥有管理员权限的 GitHub 账户。
- 一个Timestamp GIT 账户,其套餐与你的仓库可见性相匹配:Open Source(免费,公开仓库)、Pro Agency($49/月,私有仓库)或 Enterprise ZK($199/月,GitHub Actions)。
- 决定证明应该存放在哪里:同一仓库中的专用
timestamps分支,还是一个单独的影子仓库。 - 明确权限模型:标准模式需要对源仓库的只读访问权限,以及对目标仓库的读写访问权限。企业 ZK 模式仅需要对目标仓库的读写访问权限,外加在源仓库中安装的 GitHub Action。
- 基本上没有其他要求。开发者机器上无需安装任何东西。 没有本地配置,没有钩子,没有每个开发者的环境变量。
第 1 步 — 安装 Timestamp GIT GitHub App
- 导航到 Timestamp GIT GitHub App 列表页面,点击 Install。
- 选择拥有该仓库的 GitHub 账户或组织。
- 选择 Only select repositories,挑选你想要监控的仓库——或者授予对该账户中所有仓库的访问权限。
- 批准所请求的权限。在标准模式下,这意味着对源仓库的只读访问权限(GitHub 的权限系统没有“仅提交哈希”的范围),以及对写入证明的目标仓库的读写访问权限。
- 确认重定向回 Timestamp GIT,并等待成功消息。
这就是安装过程。这是一个普通的 GitHub App OAuth 式流程,大约需要一分钟。
第 2 步 — 连接并配置你的仓库
前往 Your Repositories(/repos),确认新可访问的仓库出现在列表中。如果没有显示出来,几乎可以肯定你在安装时选错了账户。
然后打开仓库连接页面,配置证明的目标位置:
- 同一仓库,专用分支——证明与你的代码一起落在
timestamps分支上。简单、自包含、易于查找。 - 单独的影子仓库——证明落在你选择的仓库中。当源仓库的受众受限,或者你想在多个项目中拥有一个中央证明账本时,这很有用。
如果你使用影子仓库,请创建或选择它,并确认 Timestamp GIT 对其拥有读写访问权限。此处权限缺失或被撤销是日后出现“为什么什么都没显示”的最常见原因。
在这个页面上,启用 README 徽章。连接页面会渲染 Shields.io 徽章的实时预览,并给你确切的 markdown 片段——不要手写 URL,因为私有仓库需要特定于实例的 HMAC 组件。
保存配置。App 现在已准备就绪:从此刻起,webhook 会告知它受监控分支上的每一次新提交。
第 3 步 — 让夜间锚定运行(并了解会发生什么)
你不需要再做其他任何事情。以下是午夜发生的过程:
- 提交检测——GitHub App 已经通过 webhook 捕获了新的提交哈希。
- 哈希队列——哈希存放在内存键值存储中,等待批处理窗口。
- 午夜 cron 工作进程——待处理的哈希被分组,为每个仓库生成一个清单
.txt文件,原生构建 Merkle 树,使用公共 OTS 日历创建 OpenTimestamps 证明,并将 Merkle 根锚定到比特币区块链中。 - 证明交付——清单文件和
.ots收据文件被推送回你仓库的timestamps分支或影子仓库。
目标仓库中出现的内容大致如下:
timestamps/
manifests/
2026-10-18.txt # 当天批处理的提交哈希
proofs/
2026-10-18.txt.ots # 该清单的 OpenTimestamps 收据
时间预期。 批处理在午夜运行,比特币确认需要几个小时——通常大约三个小时。所以如果你在 09:00 推送,预计证明会在第二天上午中段到达。这是比特币的特性,不是流水线的缺陷。
离开你仓库的内容: 只有提交哈希。Timestamp GIT 从不读取、复制或存储你的源代码。源代码留在 GitHub(或者在企业 ZK 模式下,完全留在你自己的环境中),只有哈希被加盖时间戳。
然后它会重复。每晚,永远,针对每一次未来的提交。你安装了一次;流水线处理其余的一切。
第 4 步 — 将验证徽章添加到你的 README
从仓库连接页面获取 markdown 片段——相同的数据也可以通过经过身份验证的 GET /api/badgeLink/{user}/{repo} 端点以编程方式获取,该端点返回徽章 URL 和 markdown 片段。
该片段的形式如下(使用复制按钮;实际 URL 是特定于实例和仓库的,尤其是对于私有仓库):
[](<status-page-url>)
将其粘贴到你的 README 中,提交并推送。任何点击徽章的人都会进入公开验证视图——无需账户、无需登录、无需特殊知识。
关于私有仓库的说明。 私有仓库的状态 URL 会附加加密的 HMAC。这意味着只有授权用户才能看到证明状态,而底层的比特币锚定仍然可以被任何持有 .ots 文件的人公开验证。HMAC 特定于你的服务器实例,这就是为什么你应该复制徽章 URL 而不是自己构造它。
可选但不错:将相同的徽章嵌入内部文档站点或工程仪表板。它只是一个图片 URL 加一个链接。
第 5 步 —(可选)使用 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 License 页面(/docker-license)上的请求表单,附上你的姓名、公司、电子邮件和可选的电话号码,即可获得用于评估的限时演示许可证。批准后即可下载限时演示许可证文件。
如何确认它成功了
给它一个完整的周期(午夜批处理加上大约三个小时),然后验证:
- 状态仪表板——打开
/status/{user}/{repo}。你应该看到证明存续时间、最早锚定日期、每日规律性、比特币区块和交易数据,以及日历热力图。 - 审计 CSV——
GET /api/audit/{user}/{repo}下载完整的审计账本。 - PDF 证书——
GET /api/report/{user}/{repo}/{date}为特定日期生成证书。 - Merkle 链遍历——
/verification/{user}/{repo}/{date}逐步展示多级验证过程。所有计算都在你的浏览器中本地进行,所以没有人——包括我们——能看到你验证的内容。 - 公开状态端点——快速健全性检查:
curl -s https://timestampgit.dev/api/statusLast/{user}/{repo}
curl -s https://timestampgit.dev/api/statusCount/{user}/{repo}
curl -s https://timestampgit.dev/api/statusSummary/{user}/{repo}
statusLast 返回最后锚定的比特币区块,statusCount 返回已提交和已加盖时间戳的提交总数,statusSummary 将数据打包供 Shields.io 使用。
如果你想了解将 .ots 文件转换为已验证比特币区块高度的更深入的离线演练,我们在如何在本地验证比特币时间戳证明中单独介绍。
排查常见设置问题
24 小时后没有出现证明。 确认 App 确实有权访问正确的仓库(检查 /repos),并确认在安装之后至少推送了一次提交。早于安装的提交从未被发送到哈希队列。
徽章显示为“unknown”。 检查徽章 URL 中的仓库 slug。对于私有仓库,确保加密的 HMAC 组件存在——一个被删减的 URL 将无法通过授权并返回无状态。
影子仓库推送失败。 Timestamp GIT 需要对目标仓库的读写访问权限。重新检查影子仓库的安装权限;源仓库的权限不会延伸到它。
企业 ZK 模式没有产生任何内容。 在该模式下没有基于 webhook 的提交检测。如果 GitHub Action 未安装在源仓库中并主动将哈希推送到 API,则没有任何哈希会到达服务。
证明晚了几个小时。 这是预期内的。批处理在午夜运行,比特币确认通常需要大约三个小时。这里的延迟是区块链时间问题,不是失败。
FAQ
我需要安装任何 CLI 工具或运行 OpenTimestamps 命令吗?
不需要。Timestamp GIT 是一个托管的 GitHub App:你安装一次,对受监控仓库的每一次提交都会每晚自动锚定到比特币中。没有 CLI 工具,没有 OpenTimestamps 命令,开发者机器上无需安装任何东西。
我可以将 GitHub App 与私有仓库一起使用吗?
可以。Pro Agency 套餐支持私有仓库。私有仓库的状态 URL 会附加加密的 HMAC,因此只有授权用户才能查看证明状态。
我的第一个时间戳证明出现需要多长时间?
提交由午夜 cron 工作进程进行批处理和锚定。比特币确认通常需要大约三个小时,因此清单文件和 .ots 收据文件会在批处理运行几小时后推送回你的仓库。
如果 Timestamp GIT 关闭了,我的证明会怎样?
证明是独立于供应商的。它们仅依赖 SHA-256 和通过 OpenTimestamps 协议的比特币区块数据,因此即使服务不再存在,你也可以使用标准工具离线验证它们。
结论
GitHub App 区块链时间戳设置的全部意义在于它应该是无聊的:安装一次,选择一个仓库,选择证明的去向,然后让夜间任务完成其余的工作。第 2 步之后的一切都是在等待比特币确认。
到那时,你就拥有了大多数团队没有的东西——关于你的代码何时存在的数学上不可否认的证明,可离线验证,而你的源代码从未离开你的仓库。这是你可以交给律师、审计员或客户的现有技术,而无需任何开发者改变他们的工作流程。
先在你最有价值的仓库上安装 GitHub App,然后从那里扩展。如果你更愿意在自己的边界内运行它,Docker 自托管许可证是相同的产品,只是底层基础设施由你提供。