NemoClaw 受信任 main 分支 E2E 分发全流程：运行模式、凭据边界与结果核验

本文基于仓库维护者技能 .agents/skills/nemoclaw-maintainer-e2e/references/main-runs.md，完整讲解如何在 NemoClaw 的 GitHub Actions 流水线（.github/workflows/e2e.yaml）上，为维护者请求的受信任main提交分发一次 E2E 运行。读完本文，你将掌握四种运行模式的选取规则、分发前后的凭据与资源清理边界、以ghCLI 完成“解析提交 → 单次分发 → 有界轮询 → 结果核验”的完整操作闭环，并理解Release qualification聚合作业的严格语义——它只报告运行结果，绝不替代发布决策。

适用范围：只有维护者请求受信任的main分发时才使用

本流程不是通用 E2E 入口。它只在维护者明确请求一次新的受信任maindispatch 时启用，对应技能路由表（见 SKILL.md）中的“Run the currentmaincommit on GitHub”分支。与之并列的其他入口各自独立：

关键约束：一次新的 GitHub 候选运行只能测试“最新的 PR 提交”或“当前的main提交”；任意历史提交的选择不被支持。所有 GitHub 侧运行都必须使用来自受信任main的.github/workflows/e2e.yaml，不得用本地活体 E2E 代替 GitHub 运行，除非维护者明确要求本地执行。此外，通用 E2E 请求并不自动授权Exact staging Brev Launchable路径；在分发任何包含该作业的运行之前，必须先阅读 Staging Launchable，它拥有该作业的凭据、部署、清理、产物与队列边界。

第一步：选择运行模式

分发动作由请求语义决定，而不是由“all”“complete”这类宽泛措辞推断。下表是请求到RUN_MODE、jobs、targets三个输入的权威映射：

四种模式的选择器语义必须精确理解：

• ordinary 模式：选择默认 E2E 套件，不包含Exact staging Brev Launchable。这是“跑一遍常规 E2E”的默认回答。
• focused 模式：选择具名作业（jobs）或按类型选择目标（targets），但只能设置一个选择器输入。两者同时非空、或两者同时为空都会被拒绝。
• launchable 模式：只运行staging-brev-launchable这一个作业，即预装完整 E2E 套件的 Brev Launchable 校验。
• full 模式：在默认套件之上追加Launchable 作业，也就是“完整套件 +Exact staging Brev Launchable”。

容易踩的两个坑：其一，通用 E2E 请求绝不能擅自授权 Brev Launchable 路径，不要因为请求里出现 “all” 或 “complete” 就推断为 full 模式；只有当请求中出现互相冲突的模式表述时才需要追问澄清。其二，full模式会发布严格聚合的Release qualification作业，这个作业不放宽任何失败作业——每个 release-required 作业都必须成功。它的职责只是“报告这次运行的结果”，不决定发布是否可以继续。

第二步：分发前的凭据与资源边界检查

在分发之前，必须阅读 Push and Manual PR E2E 章节，确认所选作业涉及的凭据位置、访问方式、生命周期与移除/清理边界。普通、focused 与 full 运行都可能把凭据暴露给被选中的候选作业，这些凭据可能提供推理、Brave Search、消息渠道或受作用域限制的 GitHub 访问能力。

分发前必须完成的四项检查：

1. 审查受信任的main修订——确认要测试的提交本身可接受；
2. 检查失败运行的产物——从上一轮失败中提取诊断信息；
3. 移除未清理的外部资源——目标清理流程未能移除的临时资源必须手动删除；
4. 轮换或撤销任何候选代码可能复制过的凭据——只要候选代码有机会接触过某个凭据，就要假定它已被复制。

Launchable 作业的凭据边界

Exact staging Brev Launchable作业的凭据边界非常明确（细节同样记录在 test/e2e/README.md）：

• BREV_API_KEY与BREV_ORG_ID：仅在受信任主机的准备阶段使用，用于在指定组织中执行 Brev 工作区操作；候选代码永远接触不到这对凭据。
• NEMOCLAW_IMAGE_DISPATCH_TOKEN：只以GH_TOKEN的形式暴露给受信任主机脚本，用于列出brevdev/nemoclaw-image中成功的生产者运行并下载选定的 staging handoff 产物。
• NVIDIA_API_KEY：作为公开的 NVIDIA 端点凭据，在 full E2E 中被以NVIDIA_INFERENCE_API_KEY的名称导出到 Brev guest。guest 中的候选代码可以读取并使用这个推理密钥——这一点必须在分发前明确告知维护者。

该工作流在源码检出之前就要求仓库maintain或admin权限。如果清理失败，必须删除记录的 workspace，并对仍然可能可访问的凭据执行轮换或撤销。

两个相邻作业的边界值得一提：受保护的托管镜像资质（managed-image-protected-runtime）只把NVIDIA_API_KEY提供给受信任的资质代码；如果其已验证的清理拒绝移除临时 NIM 容器，需要人工检查该容器并轮换密钥。而显式专用的staging-brev-launchable-identity作业验证真实的 Launchable 启动、SSH 访问、镜像与烘焙运行时身份，但不运行 onboarding 或推理，也不满足发布资质（见 test/e2e/README.md）。

Jetson 与 DGX Spark 默认保持禁用

标准命令中allow_jetson_dispatch=false，Jetson 和 DGX Spark 均不启用。只有获得工作流文档规定的操作员与 runner 批准后才可启用。完整的 Jetson 分发控制契约见 Jetson Dispatch Controller——NemoClaw 拥有受信任的 GitHub Actions 控制器、HTTP 契约 2.0.0、OIDC 令牌流程与证据边界，而设备侧服务属于操作员自有基础设施。另外，在 DGX Spark 资质开始前，GitHub 可能要求一个经授权的环境审查者。

第三步：解析待测提交

分发前先确认 GitHub CLI 已认证，并解析出待测试的origin/main提交：

gh auth status git fetch --prune origin main CANDIDATE_SHA="$(git rev-parse origin/main)"

这里解析出的origin/main提交就是新分发的测试对象。本流程无法选择任意历史提交：如果调用方提供了其他候选 SHA，应当如实报告本路径无法测试该提交，绝不派发不同的提交，也不代为决定发布结果。

第四步：只分发一次

设置所选模式与选择器，并用一个case语句在本地完成参数校验：

RUN_MODE='<ordinary|focused|launchable|full>' E2E_JOBS='' E2E_TARGETS='' INCLUDE_LAUNCHABLE=false case "$RUN_MODE" in ordinary) ;; focused) if [[ -n "$E2E_JOBS" && -n "$E2E_TARGETS" ]] || [[ -z "$E2E_JOBS" && -z "$E2E_TARGETS" ]]; then echo "Focused E2E requires jobs or targets, but not both" >&2 exit 1 fi ;; launchable) E2E_JOBS=staging-brev-launchable ;; full) INCLUDE_LAUNCHABLE=true ;; *) echo "Unknown E2E mode: $RUN_MODE" >&2; exit 1 ;; esac

然后生成一个关联 ID（correlation ID），并只分发一次工作流：

CORRELATION_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')" gh workflow run .github/workflows/e2e.yaml \ --repo NVIDIA/NemoClaw \ --ref main \ -f "targets=${E2E_TARGETS}" \ -f "jobs=${E2E_JOBS}" \ -f inference_mode=mock \ -f "include_staging_brev_launchable=${INCLUDE_LAUNCHABLE}" \ -f allow_jetson_dispatch=false \ -f "correlation_id=${CORRELATION_ID}"

要点：

• inference_mode=mock是分发固定的推理模式；allow_jetson_dispatch=false保持 Jetson 禁用。
• correlation_id用于在运行列表中唯一定位本次分发，且 full 模式的运行标题会带上它（E2E full main (<id>)），方便维护者无需逐个扫描作业即可找到最新的完整手动运行。
• 不要因为运行迟迟不出现就再次分发。工作流分发后到显示在列表中存在延迟，应使用下面的有界轮询来定位。

第五步：有界轮询定位运行

用有界读取（最多 30 次、每次间隔 10 秒）在运行列表中查找本次分发产生的运行，并校验它测试的提交与CANDIDATE_SHA一致：

set -euo pipefail RUN_TITLE="E2E main (${CORRELATION_ID})" if [[ "$RUN_MODE" == full ]]; then RUN_TITLE="E2E full main (${CORRELATION_ID})" fi for POLL_INDEX in $(seq 1 30); do RUNS="$(gh run list --repo NVIDIA/NemoClaw --workflow e2e.yaml \ --event workflow_dispatch --branch main --limit 50 \ --json databaseId,displayTitle,headSha,status,url)" MATCHES="$(jq -c --arg title "$RUN_TITLE" \ '[.[] | select(.displayTitle == $title)]' <<<"$RUNS")" test "$(jq 'length' <<<"$MATCHES")" -le 1 RUN_ID="$(jq -r '.[0].databaseId // empty' <<<"$MATCHES")" test -z "$RUN_ID" || break sleep 10 done test -n "${RUN_ID:-}" RUN_SHA="$(jq -r '.[0].headSha' <<<"$MATCHES")" test "$RUN_SHA" = "$CANDIDATE_SHA"

这段脚本同时实现了三个约束：

• 通过标题精确匹配找到本次分发（$RUN_TITLE内含 correlation ID），且最多允许一条匹配（length <= 1），防止同名运行干扰；
• 轮询次数有界（30 次 × 10 秒），不会无限等待；
• headSha与CANDIDATE_SHA的相等性比较证明了所选运行实际测试的提交。

需要注意：SHA 比较是“验证测试对象”的手段，不是标签授权规则。如果运行在有界搜索窗口内没有出现，应直接去 GitHub Actions 中按 correlation ID 人工排查，不要再次分发。

定位后等待运行完成：

gh run watch "$RUN_ID" --repo NVIDIA/NemoClaw

Launchable 并发组语义

Launchable 并发组（staging-brev-launchable-cpu，同时被两个 Launchable 作业与.github/workflows/staging-launchable-full.yaml共享）采用queue: max与cancel-in-progress: false：同一时刻只运行一个条目，最多保留 100 个待处理条目，条目按进入顺序执行（该顺序可能与工作流分发顺序不同），队列满时 GitHub 会取消新进入的条目。此外，每次 full/focused Launchable 分发都使用github.run_id作为工作流并发身份，因此等待期间不会有其他分发将其取代。

第六步：核验与报告

运行完成后，把运行与最新尝试的作业保存到私有证据目录（模式0700），读取时使用 GitHub API 而不是浏览器：

EVIDENCE_DIR="$(mktemp -d)" chmod 700 "$EVIDENCE_DIR" trap 'rm -rf "$EVIDENCE_DIR"' EXIT gh api "repos/NVIDIA/NemoClaw/actions/runs/$RUN_ID" >"$EVIDENCE_DIR/run.json" gh api "repos/NVIDIA/NemoClaw/actions/runs/$RUN_ID/jobs?filter=latest&per_page=100" \ >"$EVIDENCE_DIR/jobs.json"

核验标准：

• 所选运行必须报告head_sha等于CANDIDATE_SHA，且status等于completed；
• ordinary、focused、Launchable 或 full 运行的成功标志是工作流结论conclusion为success；否则需要逐个返回每个 failed、cancelled、skipped 或 running 的作业及其 URL；
• launchable 模式额外要求存在一个完成且成功的Exact staging Brev Launchable作业，并保留launchable-e2e.json、full-e2e.log与cleanup.json三类诊断产物的链接；
• full 模式额外要求存在一个完成且成功的Release qualification作业。被跳过（skipped）、取消（cancelled）、排队（queued）或失败（failed）的聚合结果都不算通过的 full 运行。

最终向维护者返回：

• 模式与选择器（RUN_MODE、jobs、targets）；
• 被测 SHA；
• 工作流状态、结论、尝试次数与 URL；
• 相关作业 URL。

Release qualification的严格语义（源码级印证）

“严格”不是一句口号，仓库里有一组专门的单元测试约束它的行为。在 test/e2e/support/release-qualification.test.ts 中可以看到：

• 任何 release-required 作业失败都会让聚合失败：测试"rejects a failure in any release-required E2E job"把staging-brev-launchable置为failure后断言抛错Release qualification did not pass: staging-brev-launchable；
• 非 success 状态一律不算通过：failure、cancelled、skipped、甚至缺失（undefined）都被归为unknown状态，记录到签收（receipt）中；
• 聚合只做报告：assertReleaseQualification输出签收并返回状态，但流程语义明确“它不授权或拒绝一个 tag”；同一文件的测试还验证了无效作业 ID 列表、空选择（视为成功的控制器级 no-op）、以及重复写签收文件时抛出EEXIST防止覆盖证据。

这与 test/e2e/README.md 的说明一致：Release qualification等待每一个不需要单独 opt-in 的 E2E 作业（包括Exact staging Brev Launchable），报告 full 运行是否通过，但不授权、不拒绝发布。做出发布决策时，应报告最新可识别的 full 运行的时间戳、被测提交 SHA、工作流结果、Release qualification结果以及每个未成功的作业，并将被测 SHA 与发布候选对比——但不要求二者必须匹配，也不施加陈旧性阈值。维护者可以基于报告继续推进、重跑 focused 作业或请求另一次 full 运行。

操作红线总结

1. 只分发一次：不因运行出现慢而重复分发；定位失败就按 correlation ID 去 Actions 里查。
2. 不越权选择：只能测origin/main当前提交；不测历史提交，不替维护者决定发布结果。
3. 不推断模式：通用 E2E 请求不授权 Launchable；只有请求包含冲突模式表述时才追问。
4. 分发前清账：审查修订、检查失败产物、移除残留资源、轮换可能被复制的凭据。
5. 报告即终点：返回模式、SHA、状态/结论/尝试/URL 与作业 URL 后收尾；Release qualification只报告运行，nemoclaw-maintainer-cut-release-tag技能才拥有常规 E2E 决策权，并会在签署的发布简报中记录任何“在异常状态下继续推进”的理由。