CI · XB 现场笔记

CI 产物需要明确的交接契约

Fri, 03 Sep 2027 00:00:00 +0000

CI 的上游任务可以成功结束，下游却拿到错误文件。产物是某个步骤生成并保存下来、交给其他任务、人员或发布流程使用的输出，仅靠名字通常不足以识别它。应把交接视为一份契约，说明生产它的运行、源码版本、负载内容、完整性证据、访问策略和可用时间窗口。这样，“下载构建结果”才成为能够核对的操作，而不是在共享目录里猜测哪个文件最新。

分清传递目的与保存期限

产物可以是二进制、测试报告、覆盖率数据，也可以是之后进入发布流程的软件包；不能断言它天然不属于发布输入。依赖缓存的目的则是加速可以重建的工作，二者不应混为一谈。选择存储和保留期之前，先确定审批、诊断和回滚需要哪些文件、需要多久。过期以后重新构建，可能生成不同字节，也需要重新验证，不能把重建视为取回原产物。

GitHub Actions 允许自定义产物保留时间，但受到仓库、组织或企业上限约束。安排流程时，要按真实配置考虑周末和延迟审批；请求一个较长保留值，并不能突破平台上限。确实需要长期留存的发布输入，应转入项目使用的持久发布存储或对象存储，并明确生命周期。短期任务存储即使今天能下载，也不应被说明成无限期的发布归档。

坏掉的样子

随手下载“最近一次成功运行”，可能拿到另一个提交、分支或工作流的文件。应明确解析目标生产任务，并核对它的源码与当前批准发布的变化之间的关系。下游还需要等待所需文件真正产生；空上传、缺失产物不能悄悄变成部署工作区里碰巧残留的旧文件。任务变绿与正确负载已经交付，是需要分别检查的事实。

完整性与来源真实性回答不同问题。校验和可以发现负载变化，但能同时替换文件和校验和的人，也能造出自洽的一对文件。来源声明还需要验证它指向的产物、签名方或工作流身份，以及项目要求的策略。二进制旁边存在一份证明文件，并不代表消费方已经执行了验证。必须看真实的验证结果，而不是只看相关配置或附件存在。

谁能访问产物，取决于平台、仓库可见性与授予的权限，不能一概等同于“能看到工作流的人”。即便如此，也只应上传交接必需的文件。凭据、环境变量全集、私有请求头和未经筛选的日志，一旦打包就可能留下额外副本。保存之前要检查成员列表及其内容，尤其当构建输入来自尚未信任的贡献时，不能只靠压缩包名称判断它是否适合交给下游。

快速验证

保存脚本为 artifacts.py 并执行 python3 artifacts.py，只需 Python 标准库。生产方在临时目录创建 ZIP，包含 app.txt 与清单；清单记录本地运行编号、示意性的源码摘要和负载摘要。消费方只读取约定成员，先比较预期生产者，再返回实际负载。这里没有解压任意归档成员，也没有连接真实 CI 平台。

from hashlib import sha256
from pathlib import Path
from tempfile import TemporaryDirectory
from zipfile import ZipFile
import json

payload = b'local build output\n'
source_digest = sha256(b'example source revision\n').hexdigest()
manifest = {'producer_run': 'local-run-41', 'source_sha256': source_digest,
 'files': {'app.txt': sha256(payload).hexdigest()}}


def produce(path, data):
 with ZipFile(path, 'w') as archive:
 archive.writestr('manifest.json', json.dumps(manifest, sort_keys=True))
 archive.writestr('app.txt', data)


def consume(path, expected_run):
 with ZipFile(path) as archive:
 if sorted(archive.namelist()) != ['app.txt', 'manifest.json']:
 raise ValueError('unexpected member set')
 received = json.loads(archive.read('manifest.json'))
 if (received['producer_run'] != expected_run
 or received['source_sha256'] != source_digest):
 raise ValueError('producer identity mismatch')
 data = archive.read('app.txt')
 if sha256(data).hexdigest() != received['files']['app.txt']:
 raise ValueError('payload digest mismatch')
 return data


with TemporaryDirectory() as directory:
 archive = Path(directory) / 'handoff.zip'
 produce(archive, payload)
 assert consume(archive, 'local-run-41') == payload
 rejected = []
 try:
 consume(archive, 'local-run-42')
 except ValueError as error:
 rejected.append(str(error))
 produce(archive, payload + b'changed\n')
 try:
 consume(archive, 'local-run-41')
 except ValueError as error:
 rejected.append(str(error))
 archive.unlink()
 try:
 consume(archive, 'local-run-41')
 except FileNotFoundError:
 rejected.append('artifact missing')
 assert rejected == ['producer identity mismatch', 'payload digest mismatch', 'artifact missing']
 print(json.dumps({'valid_payload_bytes': len(payload), 'rejected': rejected,
 'platform_retention_tested': False}))

正常交接返回十九字节。用 local-run-42 去领取实际来自 local-run-41 的归档，会得到生产者身份不匹配；保留旧清单、替换文件内容，会得到摘要不匹配；删除归档后继续下载，则得到文件缺失。最终结果必须列出这三种拒绝情况，任何失败都不会转而消费另一个构建。这样可以看清下游契约的失败分支确实执行了。

这是实际的本地归档实验，没有执行 GitHub 的过期服务，也没有生成或验证来源证明。示例源码摘要只是标识符，不是已经核实的 Git 提交。能改写清单的一方仍可能构造一致的谎言。本地删除模拟的是“文件不存在”，不能证明平台会在某个准确时刻执行过期清理。这些界限应随结果一起说明，避免把有限检查扩大成完整供应链验证。

把消费方的发布门写清楚

需要阅读实际下载组件怎样处理失败。GitHub 文档说明，摘要不一致时会在界面和任务日志中展示警告，不能直接假设所有完整性警告都会让部署失败。若发布策略要求拒绝，就应落实对应门禁，并把结果与生产者身份一起保存。还要记录持久发布字节放在哪里、谁能取回，以及临时交接副本什么时候可以过期；这些信息才能让后续审批和恢复真正依赖同一份产物。

来源

GitHub: store and share workflow data，产物传递、保留期限制和摘要校验，已核验 2026-09-13。
GitHub: artifact attestations，构建来源证据及其验证边界，已核验 2026-09-13。

GitHub Actions 工作流给构建把门槛

Thu, 02 Sep 2027 00:00:00 +0000

工作流能够为合并决定提供证据，但只有 YAML 并不会让这些证据成为强制要求。可靠的构建门禁需要连接正确的事件、实际测试的准确版本、有意义的测试结果，以及要求对应检查通过的仓库规则。审阅时应把这些环节一起核对，不能看到早先某次运行有绿色标志，就认为这次拟合并的内容已经满足当前要求。

区分执行与强制要求

.github/workflows/ 下的文件描述触发器和作业。on 选择事件，分支保护或规则集则另行决定合并之前必须通过哪些检查。应记录稳定的检查名称，并在改名时同时审阅相应规则。不同工作流也应避免产生含糊的同名作业；如果规则指定检查来源，还需确认结果确实由预期的可信应用提供。

还要查看合并请求检查框显示的版本。pull_request 运行通常检查的是合成的合并提交，而不只是贡献者分支末端。合并队列为候选组合生成检查时，需要独立的 merge_group 事件。本地构建成功，或者手动触发过某份工作流，都不能自动替代规则要求的事件与版本；检查对象不一致时，即使输出相同，也不构成同一次验证。

明确依赖结果

没有依赖的作业可以并行运行，单个作业里的步骤通常顺序执行。needs 建立前置关系，条件控制失败或跳过之后哪些工作仍会执行。只有一个必需测试作业的工作流，并不需要人为增加依赖作业，也不必额外添加事件条件。因此，把缺少这些字段一律判成错误的检查器，无法准确判断门禁是否有效。

如果使用汇总门禁，应等待每个必需作业，并显式检查其结果。通过 if: ${{ always() }} 避免前置失败后只把门禁跳过，再要求结果确实为成功。如果某项可选工作允许跳过，应明确编码这个例外，而不是把所有缺失结果都视为通过。必需测试也不能随意开启忽略错误，否则一条普通的成功提示就可能掩盖没有完成的验证。

权限声明约束令牌，不约束所有凭据

permissions 控制的是 GITHUB_TOKEN，不会限制另行传给命令的其他秘密凭据。严格的工作流级声明可以由作业继承，不需要每个作业机械重复同样内容。只有真正需要的地方才增加权限。下面的离线实验没有检出私有源码，也不调用 GitHub 接口，因此不使用令牌；真实项目接入源码时，应重新检查实际最低权限需求。

普通的复刻仓库合并请求通常收到只读令牌，而不会收到仓库秘密，具体仍受仓库设置影响。“秘密只读”不是准确说法，令牌权限与秘密可用性是两个问题。不能为了取得秘密，就改用具有更高权限的 pull_request_target 并执行不可信的请求代码。日志遮盖只是辅助保护，不是打印凭据的许可，也不保证经过转换后的值绝不会泄漏。

坏掉的样子

整个工作流因路径或分支过滤没有运行时，对应必需检查可能一直等待；作业因条件而跳过，却可能在没有执行测试的情况下满足检查规则。这是两种不同结果。修改检查名称时应小心，并在托管服务上验证失败、跳过和取消路径，不能只用一次成功运行证明规则配置正确。检查能否出现、是否真正运行和能否阻止合并，需要分别确认。

缓存需要兼容的键，也需要按依赖声明执行可靠安装。普通合并请求产生的缓存属于该请求的合并引用，仅仅键相同，并不意味着基础分支可以恢复它。不能笼统声称任何复刻请求缓存都能污染主分支；应结合事件、引用范围和信任关系判断风险。另外，测试取消与部署恢复也不同：取消正在运行的作业，不会自动撤销它已经产生的外部变化，重试必须了解实际完成到了哪里。

快速验证

下面实验单独检查一项汇总门禁决定：只有前置作业的结果严格等于 success 才接受。在真实工作流中，这个值应来自 needs.test.result，并通过 needs 声明前置依赖。这里的输入则刻意采用合成状态，是本地判断练习，不是工作流校验器，也不能替代项目真实测试。它不会安装工作流或启动托管运行，只让这一项判定逻辑能够独立复现。

把下面仅用标准库的探针保存为 gate_check.py，在有 Python 3 和 Bash 的环境运行 python3 gate_check.py。它向同一条 Shell 判断传入合成结果，并包括一个故意失败的测试断言。程序不写文件，不访问任何服务，也不使用真实仓库凭据；需要的解释器和 Shell 必须已经可用。

import os
import subprocess
import sys

subprocess.run([sys.executable, "-c", "assert 2 + 2 == 4"], check=True)
negative = subprocess.run([sys.executable, "-c", "assert 2 + 2 == 5"],
 capture_output=True, text=True)
assert negative.returncode != 0 and "AssertionError" in negative.stderr
print("test-negative-control: rejected")
command = 'test "$TEST_RESULT" = success'
for result in ("success", "failure", "cancelled", "skipped", "", "unexpected"):
 run = subprocess.run(["bash", "--noprofile", "--norc", "-c", command],
 env={"PATH": os.environ["PATH"], "TEST_RESULT": result},
 capture_output=True, text=True)
 accepted = run.returncode == 0
 assert accepted == (result == "success"), (result, run)
 print(f"{result or '<missing>'}: {'accept' if accepted else 'reject'}")
print("PASS: local predicate only; GitHub enforcement not exercised")

预期故意失败的测试被拒绝，只有 success 被接受，最后输出范围提醒。缺失、异常、失败、取消及跳过结果都不能被当成真实成功。这证明了本地命令和拒绝分支，但没有解析任意 YAML、求值 GitHub 表达式、调度作业、读取仓库规则，也没有证明线上合并会被阻止。这些仍需针对真实仓库配置进行托管集成检查，不能用离线探针的成功代替。

来源

GitHub：工作流语法，依赖、条件和令牌权限继承，已核验 2026-10-15。
GitHub：Actions 入门，工作流、事件、作业和步骤，已核验 2026-10-15。
GitHub：排查必需状态检查，版本身份、跳过检查和合并队列，已核验 2026-10-15。
GitHub：工作流事件，复刻请求和高权限触发器的边界，已核验 2026-10-15。
GitHub：依赖缓存，分支与合并请求缓存范围，已核验 2026-10-15。
GitHub：使用秘密，秘密可用性与日志处理，已核验 2026-10-15。

先复制依赖输入，再复制应用代码

Tue, 17 Aug 2027 00:00:00 +0000

Dockerfile 顺序决定昂贵构建操作依赖哪些先前输入。如果应用源码在依赖安装之前被复制，即使依赖声明未变，修改源码也可能让安装重跑。先复制依赖输入、安装依赖，再复制应用代码，可以建立更小的依赖边界，让它与安装器真正需要的工作匹配。这里优化的是依赖关系，而不只是把几行命令挪到看起来更整齐的位置。

坏掉的样子

在软件包安装前使用宽泛的 COPY . .，会让文档、生成输出或无关源码编辑，都可能成为重做昂贵工作的原因。问题不在于 COPY 天生很慢，而在于后续安装依赖了一份包含无关变化的文件系统状态。这些变化并不是选择和安装依赖所必需，却通过前置步骤扩大了失效范围。

如果安装还读取锁文件、本地包源码、补丁、工作区元数据或包管理器配置，仅复制一个清单也不够。遗漏真实输入，可能保留已经不符合构建意图的缓存结果。正确边界必须包含安装器实际使用的全部输入，而不是只选择常见 Dockerfile 示例里出现的某个文件名。否则，表面命中率提高，实际正确性却下降。

缓存顺序也不能修复可变依赖。相同安装命令可能一直保留旧结果，而干净构建却从远端解析到不同内容。固定版本和校验哈希解决产物选择问题，控制 COPY 顺序解决复用问题。两者都需要处理，构建更快并不能证明软件包图可复现，也不能证明依赖已经更新到本次发布要求的版本。

快速验证

使用宿主 Python、Docker 构建器和已取得的固定基础镜像运行脚本。它先通过 HTTPS 下载两个公开的 idna wheel，并在构建前验证固定 SHA-256。容器构建关闭网络，pip 从本地 wheel 目录安装，并强制要求哈希。实测环境为 Docker 29.3.1，Linux arm64 基础镜像内 Python 为 3.11.16：

from pathlib import Path
from tempfile import TemporaryDirectory
from urllib.request import urlopen
import hashlib,json,subprocess,uuid

BASE='python@sha256:528257d48c1da0dcecc2e725d1ae34498d60c965f1241e39cd6a85a8859bdf84'
WHEELS={
 '3.10':('https://files.pythonhosted.org/packages/76/c6/c88e154df9c4e1a2a66ccf0005a88dfb2650c1dffb6f5ce603dfbd452ce3/idna-3.10-py3-none-any.whl','946d195a0d259cbba61165e88e65941f16e9b36ea6ddb97f00452bae8b1287d3'),
 '3.11':('https://files.pythonhosted.org/packages/0e/61/66938bbb5fc52dbdf84594873d5b51fb1f7c7794e9c0f5bd885f30bc507b/idna-3.11-py3-none-any.whl','771a87f49d9defaf64091e6e6fe9c18d4833f140bd19464795bc32d966ca37ea')}
def docker(*args,check=True):
 result=subprocess.run(['docker',*args],capture_output=True,text=True,timeout=120)
 if check:assert result.returncode==0,result.stderr
 return result

name='xbcatm-order-'+uuid.uuid4().hex[:10];tags=[name+':early',name+':late']
try:
 with TemporaryDirectory(prefix=name+'-') as directory:
 root=Path(directory);(root/'wheels').mkdir()
 for version,(url,digest) in WHEELS.items():
 with urlopen(url,timeout=40) as response:data=response.read()
 assert hashlib.sha256(data).hexdigest()==digest
 (root/'wheels'/url.rsplit('/',1)[1]).write_bytes(data)
 install='RUN pip install --no-index --no-deps --require-hashes --find-links=/wheels -r /app/requirements.txt && python -c "import time;open(\'/installed\',\'w\').write(str(time.time_ns()))"\n'
 common=f'FROM {BASE}\nLABEL example.run="{name}"\nCOPY wheels /wheels\n'
 (root/'early.Dockerfile').write_text(common+'COPY requirements.txt app.py /app/\n'+install+'CMD ["python", "/app/app.py"]\n')
 (root/'late.Dockerfile').write_text(common+'COPY requirements.txt /app/\n'+install+'COPY app.py /app/\nCMD ["python", "/app/app.py"]\n')
 def requirement(version):
 (root/'requirements.txt').write_text(f'idna=={version} --hash=sha256:{WHEELS[version][1]}\n')
 def application(message):
 (root/'app.py').write_text(f'import idna\nprint({message!r},idna.__version__,idna.encode("bücher.example").decode())\n')
 def build():
 for tag,kind in zip(tags,['early','late']):docker('build','--network','none','-f',str(root/(kind+'.Dockerfile')),'-t',tag,str(root))
 def marks():
 return [docker('run','--rm','--network','none',tag,'cat','/installed').stdout for tag in tags]
 requirement('3.10');application('first');build();first=marks()
 application('second');build();second=marks()
 assert first[0]!=second[0] and first[1]==second[1]
 for tag in tags:assert docker('run','--rm','--network','none',tag).stdout.strip()=='second 3.10 xn--bcher-kva.example'
 print('editing only application code reruns the early-copy dependency install but reuses the late-copy install')
 requirement('3.11');build();third=marks()
 assert all(a!=b for a,b in zip(second,third))
 for tag in tags:assert docker('run','--rm','--network','none',tag).stdout.strip()=='second 3.11 xn--bcher-kva.example'
 print('changing the hashed requirement reruns both installs and actually changes idna from 3.10 to 3.11')
finally:docker('image','rm',*tags,check=False)

提前复制版本的 Dockerfile 在 pip 之前一起复制 requirements.txt 与 app.py。延后复制版本先复制依赖声明，执行相同安装命令，再复制应用。两者都提前加入经过验证的 wheel 目录，因为这些文件确实是安装输入。pip 之后立即写入标记，用来观察安装所在操作是否真的执行，而不是凭耗时猜测。

初始应用使用 idna 3.10 编码 bücher.example。两个镜像都调用实际安装的库，得到预期 ASCII 域名 xn--bcher-kva.example。这验证真实第三方依赖，不用 sleep 代替安装，也不把镜像构建成功直接当成应用能够导入软件包的证明。运行结果同时包含版本，能够确认到底安装了哪个版本。

只把应用消息从 first 改为 second 后，两个镜像都输出新消息和版本 3.10。提前复制的镜像得到新的安装标记，延后复制的镜像保留原标记。程序输出证明源码变更已进入两份镜像，标记比较则指出哪一份布局重复执行了不必要的依赖工作。这样可以排除“缓存太多导致应用没更新”的错误解释。

接着，把依赖声明改为 idna 3.11 和对应哈希。两份安装标记都改变，应用也都报告 3.11，并继续得到相同预期域名转换。这是必须验证的相反情况：真实依赖声明变化，在两种布局下都应让安装失效。如果某个布局忽略了这项输入，即使很快也不正确，不能只用源码修改时的成功缓存来评价它。

两个 wheel 从实验开始就一起提供，因此修改 requirement 不会同时改变 wheel 目录，第二次失效的原因保持明确。结束时清理临时镜像与文件，不清理其他构建器状态。安装时间戳只是测试观测手段，不是建议给生产可复现产物增加的随机输入；正式构建应去掉这类只为证明执行次数而加入的标记。

让缓存边界对应软件包边界

审查安装器会读取什么，再把这些输入放到安装操作之前。让无关文件留在该 COPY 范围之外，并用 .dockerignore 排除构建完全不需要的材料。被忽略的文件之后无法满足必需 COPY，因此当某个依赖明明在工作区却构建不可见时，应检查真实构建上下文，而不是不断加禁用缓存选项。

包管理器缓存挂载，可以在安装确实需要重跑时减少下载，但不能替代正确失效规则或输出校验。依赖安装结果复用与下载缓存复用，是不同层次的优化；修改任意一层后，都应运行最终应用验证。不能因为下载更少，就认定安装状态一定与新的锁文件一致。

用有代表性的构建测量效果：完全相同输入、只改源码、升级依赖。三种情况都保留正确性断言。有效的 Dockerfile 应让必要工作重新执行，让不必要工作继续复用，并提供足够证据区分两者。这样，构建性能的改进才能与实际发布内容保持一致。

来源

Optimize Docker cache usage，稳定依赖层与窄范围 COPY，已核验 2026-09-12。
Docker cache invalidation，变化输入如何使后续依赖工作失效，已核验 2026-09-12。
pip install reference，离线 wheel 安装与强制哈希校验，已核验 2026-09-12。

CI · XB 现场笔记

CI 产物需要明确的交接契约

分清传递目的与保存期限

坏掉的样子

快速验证

把消费方的发布门写清楚

延伸阅读

来源

GitHub Actions 工作流给构建把门槛

区分执行与强制要求

明确依赖结果

权限声明约束令牌，不约束所有凭据

坏掉的样子

快速验证

延伸阅读

来源

先复制依赖输入，再复制应用代码

坏掉的样子

快速验证

让缓存边界对应软件包边界

延伸阅读

来源