GitHub Actions 会把 Runner 应用日志和单个 Job 的日志分别写入 _diag 目录，文件名以 Runner_ 和 Worker_ 开头。GitHub 官方排查文档 这给出了明确的排查起点：先确认 Runner 实际使用的 macOS 账户及其钥匙串状态，再核实签名身份和描述文件。本地终端能签名，不代表 CI 作业也能访问相同凭据。不要靠扩大权限或反复导入证书来碰运气。
本文适合本地能签名、GitHub Actions 却无法归档或签名的 iOS/macOS 开发者；负责自托管 Mac Runner、需要复核执行账户和签名环境的 DevOps 工程师；以及要区分证书、私钥、钥匙串和描述文件责任的发布或凭据管理员。
[ SECTION_01 ] 先按故障阶段划分责任
一次签名失败并不等于证书坏了。先从失败 Job 里确定故障落在哪个阶段：构建、归档、选择签名身份，还是最终签名。构建失败应先看项目配置和构建参数；归档失败要核实目标与归档设置；只有日志明确指向身份、私钥、钥匙串或配置文件时，才把排查重点转到签名材料。
开发者应固定本地与 CI 对照的提交、Scheme、Target、构建配置和归档目标。CI 维护者则记录 Job 实际使用的 Runner 标识和执行账户。缺少同一提交、同一目标的对照，日志中的差异很容易被错误归因给证书。
GitHub 的自托管 Runner 文档说明，每个 Job 都有对应的详细日志；应用启动与运行状态也有单独日志。先保留这两类记录，后续交接时才有证据区分“Runner 服务上下文异常”和“项目选择了错误的签名配置”。
[ SECTION_02 ] 开发者先确认项目要签什么
先对照 Xcode 中的 Scheme 和 Target，再看 Workflow 实际传入的构建参数。自动签名与手动签名是两条不同路径：不能一边让项目自动管理描述文件，一边又让构建参数指定另一份配置文件，并假定两边会自动一致。
Apple 的构建设置文档列出与签名相关的设置，包括 CODE_SIGN_IDENTITY、DEVELOPMENT_TEAM 和 PROVISIONING_PROFILE_SPECIFIER。这些值可能来自项目、配置文件或命令行参数；因此应以 CI 构建日志中实际生效的设置为准，而不只看 Xcode 界面里保存的值。(developer.apple.com)
| 核验项 | 证据与判断 | 优先级评分 |
|---|---|---|
| Scheme 与 Target | CI 选择的目标是否就是预期 App、扩展或测试目标；不同 Target 可能有不同签名设置 | ★★★★★ |
| 签名方式 | 明确当前目标走自动签名还是手动签名，检查构建参数是否覆盖项目选择 | ★★★★★ |
| Bundle Identifier 与 Team ID | 确认目标标识、开发团队与描述文件指向同一应用和团队 | ★★★★☆ |
| 描述文件用途 | 发布、开发或其他目标所需的配置文件是否与当前归档流程匹配 | ★★★★☆ |
表中星级表示建议的排查顺序，不代表故障概率或平台官方评分。Apple 的签名说明要求将团队、唯一 Bundle Identifier 与签名设置配合检查；发布配置文件也需要匹配 App ID 和签名证书。(developer.apple.com)
若本地与 CI 的构建设置不一致，先修正 Workflow 参数或项目配置，再测试一次。若这些项目设置一致，但 CI 找不到身份或无法使用私钥，应将问题交给 Runner 与签名材料负责人，不要继续改项目配置来掩盖主机差异。
[ SECTION_03 ] Runner 维护者核对执行账户和钥匙串
SSH 登录成功只能证明该 SSH 会话可工作。它不自动证明 GitHub Actions 的服务进程以同一个用户运行，也不证明该进程能访问登录会话中的 macOS Keychain。服务启动方式、账户、主目录和钥匙串状态不一致，都可能造成“本地可签名、CI 不可签名”。
在 Workflow 中加入受控的诊断步骤，记录当前账户、主目录、Runner 标识，以及钥匙串列表和状态；不要打印秘密、证书私钥或密码。再对照 Runner 服务配置及 _diag 中与该次作业对应的日志。GitHub 文档指出，macOS Runner 服务使用 launchd 管理，且自定义服务应使用 Runner 提供的 runsvc.sh 入口。检查服务状态时，应以实际安装的服务配置和日志为准，而非仅凭桌面已登录或 SSH 测试成功。(docs.github.com)
| 观察到的结果 | 责任交接 | 下一步 |
|---|---|---|
| Workflow 的账户或主目录与预期不同 | Runner 维护者 | 核查服务启动账户与服务配置，再在相同执行上下文中复测 |
| 账户一致，但钥匙串不可用或状态异常 | Runner 维护者与凭据管理员 | 确认该账户能访问预期钥匙串，并核对作业运行时钥匙串状态 |
| 身份不可见，或身份无法用于签名 | 凭据管理员 | 检查身份与私钥配对、有效性及该钥匙串的访问控制 |
| 身份可用，但描述文件或目标不匹配 | 开发者与发布负责人 | 对照目标标识、Team ID、签名用途和归档目标 |
| 项目、身份与描述文件均匹配，仍有失败 | 发布负责人 | 保存完整日志与产物检查结果，再判断是否需要隔离或重建节点 |
如果 Runner 以服务方式运行，GitHub 的服务文档提供了 macOS 服务配置参考文件路径；核验时，应避免把 SSH 终端中的状态直接当成服务进程状态。
⚠️ 钥匙串修复可能改变凭据的可见范围。调整之前先记录原状态、操作人和回滚办法；不要为了让报错消失而对共享节点上的所有任务开放签名私钥。
[ SECTION_04 ] 签名管理员检查身份与描述文件是否成对
macOS 代码签名身份不是一张证书的别名。Apple 将身份说明为证书与对应私钥的组合；证书存在但缺少匹配私钥，或当前执行环境无法使用私钥，都不足以完成签名。应在 Runner 实际作业上下文里检查身份，而不是只在管理员自己的桌面账户里确认文件存在。(developer.apple.com)
Apple 的代码签名技术说明提供了 security find-identity 这类身份检查线索，也指出身份搜索范围会受指定钥匙串影响。若检查命令能列出身份，仍需继续确认该身份是否适用于当前代码签名、私钥能否被作业访问，以及构建实际选中的是不是这一项。命令输出可以帮助定位，不能单独证明归档产物已正确签名。(developer.apple.com)
随后核对描述文件的 App ID、团队和用途。Apple 的发布流程要求 App ID 与 Bundle Identifier 匹配，并选择相应签名证书；因此“证书身份存在”与“描述文件适用于这个归档目标”是两项独立检查。(developer.apple.com)
如果必须更新或重新导入签名材料，先保存变更记录并确认恢复路径。只有在证据表明身份或描述文件本身不匹配、失效或无法使用时，才变更材料；不要把重复导入当成通用修复方案。
[ SECTION_05 ] 凭据管理员限制谁能触发签名作业
签名故障的处理不能以牺牲凭据安全为代价。先梳理哪些仓库、分支、工作流和人员能够触发含签名凭据的 Job，再确认 Runner 是否与不可信任务共享。GitHub 明确提醒，自托管 Runner 可能被工作流中的不可信代码持续影响；签名凭据留在这类执行环境中，会扩大影响范围。(docs.github.com)
优先收紧 Runner 组可访问的仓库与工作流，缩小凭据可见范围，并限制未受信任的代码进入签名任务。不要通过关闭保护、向所有仓库开放 Runner 或放宽私钥访问控制来“修复”一次签名失败。每次权限调整都应记录授权人、适用范围和回滚方法；如果无法确认共享节点上的代码可信，应暂停在该节点执行生产签名。
[ SECTION_06 ] 发布负责人用真实归档验收修复
编译成功不等于签名成功，Runner 显示在线也不等于发布链路正常。修复验收应使用真正的发布目标，从受信任的干净 Workflow 运行中完成构建与归档；再根据构建日志、身份检查结果和归档产物核对签名。
可勾选的复测清单
- [ ] 本地与 CI 使用相同提交、Scheme、Target 和发布配置。
- [ ] 已从 Workflow 输出确认 Runner 标识、执行账户和主目录。
- [ ] 已核对 Runner 服务及对应 Job 日志，而非只用 SSH 终端验证。
- [ ] 已确认预期身份包含可用的匹配私钥，并由 CI 实际使用。
- [ ] 已核对 Bundle Identifier、Team ID、签名方式与描述文件用途。
- [ ] 已确认涉及的凭据只对可信仓库与工作流可见。
- [ ] 已用真实发布目标生成归档，并检查签名与交付产物。
- [ ] 已记录变更、复测结果与失败时的回滚或隔离办法。
只有清单中的关键项都能由日志或产物证明，才恢复生产发布。如果服务账户或权限边界仍不可复核，先隔离签名任务或迁移到专用节点。若团队还在评估远程执行环境，可先查看 NOVAKVM 的远程 Mac 方案，并对照 Mac 方案与采购信息判断是否符合实际运维要求。
[ SECTION_07 ] 何时改用专用远程 Mac 节点
本地开发机兼作 Runner，排查时容易把桌面会话、个人钥匙串和 CI 服务混在一起；共享自托管节点则会让凭据可见范围和残留环境更难管理。Linux 云主机可以运行通用任务，却不能替代需要 Xcode 与 macOS 工具链的 iOS 代码签名流程。
若问题根源是执行环境长期不稳定，专用远程 Mac 节点能把 CI 的 macOS 账户、服务上下文和签名验收集中管理，也可通过 SSH 或远程桌面处理维护任务。通过 NOVAKVM 租用节点适合需要临时测试或希望先搭建隔离签名环境的团队；若任务是长期稳定的高负载运行，或必须直接连接本地物理设备与接口，则应评估自购 Mac 或保留本地专用设备，不必为了租赁而迁移。租用前先确认执行账户、钥匙串访问、节点隔离和归档验收都能纳入团队流程。