症状： GitHub Agentic Workflows 的 Agent 作业要运行 Xcode，却发现 macOS Runner 不受支持。
最快解法： 把 Agent 作业放在受支持的 Linux Runner 上处理仓库任务，再用独立的常规 GitHub Actions macOS 作业执行 Xcode 构建与测试；通过同一工作流依赖或经过校验的跨工作流产物完成交接。
维护 gh-aw 仓库自动化的工程师：判断 Agent 工作流能否承担 Xcode 任务。
负责 Apple 平台 CI 的开发者：安排 Xcode 构建与测试的 macOS 执行环境。
研发平台负责人：设计 Linux Agent 与 Mac Runner 之间的交接和权限边界。
最后核对：2026 年 10 月 25 日。 Runner 支持状态、workflow_run 触发条件与产物下载规则，依据 GitHub Agentic Workflows 官方 FAQ、Runner 配置文档及 GitHub Actions 工作流事件文档核对。
SECTION 01先把执行边界划清
能在 Mac 上安装 gh-aw CLI，不等于 Agent 工作流可以在 macOS Runner 上执行。官方说明，Agent 工作流需要 Agent Workflow Firewall 提供的容器隔离，而 macOS Runner 不支持它所需的容器作业；官方建议改用 ubuntu-latest 或其他受支持的 Linux Runner，并把 macOS 专属工具步骤放进单独的常规 GitHub Actions 作业。GitHub Agentic Workflows 官方 FAQ
先区分这三层，避免把本机工具安装、Agent 执行和 Apple 工具链混成一个问题：
| 要做的事 | 合适的执行位置 | 你要关注的边界 |
|---|---|---|
| 安装、编译或检查 gh-aw 工作流定义 | 你用于开发和维护的系统；CLI 支持 macOS 等安装环境 | CLI 能安装，不代表 Agent Runner 支持 macOS |
| 让 Agent 分析仓库、整理问题、提出代码修改 | 受支持的 Linux Runner | 按 Agent 工作流定义配置触发条件、工具、权限和安全输出 |
| 运行 Xcode 构建、Apple 平台测试等 macOS 专属步骤 | 独立的常规 GitHub Actions macOS 作业 | 这是普通 Actions 作业，不是 gh-aw Agent 作业 |
Agent 工作流与常规 Actions 的任务形态也不同：前者让 Agent 根据自然语言指令分析或生成内容，后者按明确步骤执行构建、测试等确定性任务。GitHub 的工作流机制说明介绍了两类工作的分工；因此，不要把“Agent 能写出构建命令”当成“Agent 作业能在 Mac 上执行 Xcode”。
为什么不能把 Agent 作业直接改成 macOS Runner？
因为问题不只是 Runner 上有没有 Xcode。当前官方列出的限制是，Agent Workflow Firewall 依赖的容器作业无法在 macOS Runner 上运行；改一行 runs-on 并不会补上这道隔离边界。
SECTION 02试跑前，先约定交接契约
在开始配置前，先写明 Agent 产出什么、Mac 构建消费什么，以及出现不匹配时该停止还是回退。没有这个约定，即使两个工作流都显示成功，也无法确认 Xcode 测试针对的是 Agent 实际处理的那次代码。
| 交接字段 | Agent 工作流负责产生 | Mac 构建工作流负责检查 |
|---|---|---|
| 提交 SHA | 记录任务对应的 ${{ github.sha }} 或事件中的目标 SHA |
检出并构建同一个 SHA；不一致就失败 |
| 分支与触发原因 | 记录来源分支及触发事件 | 限制允许构建的分支与事件，不凭分支名猜测来源 |
| 修改与产物 | 以受控方式提交修改，或上传命名明确的交接产物 | 只取指定运行、指定产物；检查内容是否符合预期 |
| 运行结果 | 记录 Agent 作业结论及可追溯运行 ID | 检查上游工作流、结论与提交关联，再启动 Xcode 任务 |
| 构建反馈 | 接收构建结果并按策略继续后续任务 | 记录构建与测试结果，保留可关联到提交的日志或报告 |
建议把交接信息写入机器可读的清单文件，并至少包含 commit_sha、branch、source_run_id、artifact_name 和任务标识。字段名只是你们团队约定的占位示例，不是 GitHub 的特殊字段；关键是 Agent 产生、Mac 作业验证，而且校验失败时不能继续构建。
这里有个实际取舍：把源码修改通过受控提交交接，Mac 作业就按 SHA 检出代码；把文件作为 Actions artifact 交接，则要另行核对文件来源与内容。前者便于从提交历史追踪，后者适合传递测试报告或明确限定的输出文件，但不能把 artifact 名称当成来源证明。
SECTION 03Linux 上先验证 Agent 工作流
第一次运行先别接 Xcode。先选一个不会执行仓库脚本、也不需要访问 Mac 的小任务，例如归纳仓库文档或生成待审核的分析结果；这样能分别确认触发、权限、Agent 引擎认证和输出是否符合预期。
按顺序执行：
- 在工作流定义中确认触发条件、权限、Agent 引擎与工具配置；明确哪些操作只读，哪些输出需要审核。
- 使用当前版本文档支持的配置字段，设置受支持的 Linux Runner。官方 Runner 配置文档列明
macos-*不受支持，并将 Linux 作为 Agent 工作流的执行路径。 - 运行
gh aw compile，检查生成的.lock.yml是否与源工作流定义一致。官方文档说明，编译会生成供 GitHub Actions 执行的锁定工作流；不要只审 Markdown 指令而忽略实际执行的 YAML。 - 为所选 Agent 引擎配置所需认证，并把 Token 权限压到任务所需范围；先不加入签名证书、发布密钥或其他 Mac 构建凭据。
- 触发小任务，检查运行日志、权限范围、输出和最终结论；保存这次运行的提交 SHA、分支和 run ID，作为 Mac 构建接入的验证基线。
gh-aw 和常规 Actions 的 Mac 工作流怎么传递产物？
同一工作流中的作业，可以用 Actions artifacts 保存并下载文件；GitHub 的产物存储与共享说明介绍了这种跨作业共享方式。跨工作流时，必须明确指定上游运行和产物，而不是默认取“最近一次”的同名文件。
SECTION 04给 Xcode 单独接入常规 Mac CI
Mac 构建作业应写成普通 GitHub Actions 工作流，并选择你实际可用、已验证的 macOS Runner。这个作业负责检出约定的提交、准备 Xcode 工具链、执行构建与测试、上传必要结果；不要把它称为 gh-aw Agent 作业，也不要把 Agent 的自然语言结论当成构建通过证据。
最简单的编排方式是在同一常规工作流中使用 needs 关系：上游任务成功后，Mac 作业才启动；产物通过同一工作流内的 artifact 传递。若 Agent 工作流与 Mac CI 分成两个工作流，则可考虑用 workflow_run 触发后续流程，但要理解它的语义：事件仅在后续工作流文件存在于默认分支时触发，事件上下文中的 GITHUB_SHA 和 GITHUB_REF 指向默认分支，而不是自动代表上游 Agent 所处理的提交。相关行为见 GitHub Actions 工作流事件文档。
| 编排方式 | 适合的条件 | 容易遗漏的检查 |
|---|---|---|
| 同一工作流内的依赖作业 | 你能在一条流水线里安排 Agent 与 Mac 阶段 | 用 needs 限制启动条件；将 SHA 和 artifact 明确传给后续作业 |
workflow_run 后续工作流 |
需要把 Agent 和 Mac CI 独立维护或授权 | 匹配上游工作流名称与结论；检查上游 SHA、分支及 run ID；确认默认分支已包含后续工作流文件 |
用 workflow_run 触发 Mac 构建时，怎么核对上游提交？
先限制触发的上游工作流及活动类型，再从事件载荷读取上游 head_sha、分支和 id；下载时使用这个 id 指定的运行，而不是当前后续工作流的 GITHUB_SHA。构建前再比较 artifact 清单里的 SHA 与预期 SHA；不一致、来源不明或上游结论不符合策略，就停止，不要继续 Xcode 构建。
SECTION 05交接时先校验，再谈自动化
跨工作流下载产物通常需要提供 run-id；如果产物来自不同运行，还要按目标仓库配置具有所需读取权限的 Token。官方 download-artifact Action 文档说明了这些输入项；所以你需要把上游 run ID 当作交接数据的一部分，并在后续工作流中明确指定它。
交接步骤可以这样落地：
- 限定
workflow_run的workflows名称和types，只响应目标工作流及所需结论。 - 从事件载荷取得上游
head_sha、head_branch和id，并记录到日志或交接清单。 - 下载该 run ID 对应的指定 artifact；不要只按名称搜索“最新文件”。
- 校验清单中的提交 SHA 与上游
head_sha一致，分支符合允许策略，产物结构和预期文件相符。 - 通过校验后，显式检出对应 SHA 再运行 Xcode 构建与测试；将构建结论及日志关联回相同 SHA。
- 对校验失败、artifact 缺失或上游失败设置明确的失败路径，不允许静默跳过后继续发布。
⚠️
workflow_run是权限设计的重点，不是单纯的触发器。GitHub 提醒，后续工作流可能拥有写权限或访问密钥；如果它检出并执行不可信代码，或把不可信上游 artifact 当作可信脚本运行，风险会随之扩大。
因此，后续工作流尽量只读取得必要数据，将 permissions 缩到最小；需要读取上游 artifact 时，单独授予必要的 Actions 读取权限。不要让来自外部贡献者的代码在持有发布凭据的作业里直接执行；对待 artifact 时，先按不可信输入检查，不要把其内容当作命令、工作流定义或凭据来源。GitHub 的安全使用指南也提醒，workflow_run 触发的工作流应谨慎处理上游 artifact，并避免执行不可信代码。
SECTION 06用完整运行决定上线还是隔离
接入完成后，至少跑通一条端到端链路：Agent 处理约定任务、产出可追溯交接信息、Mac 作业取得正确提交并完成 Xcode 构建与测试、结果能回传并关联到原始运行。验收关注的不是某一次绿色状态，而是链路在失败、重复触发和 SHA 不匹配时是否按预期停止。
逐项检查：
- Agent 作业在受支持的 Runner 上运行，编译后的锁定工作流符合预期。
- Mac 作业确实是常规 GitHub Actions 作业，并在目标 macOS 执行环境中完成 Xcode 步骤。
- 上下游提交 SHA、分支、run ID、artifact 名称可相互追溯；有一项对不上就失败。
- Agent 失败、artifact 缺失、提交不一致或测试失败时，错误会传递到最终状态，而不是变成“无结果但通过”。
- 令牌和密钥仅授予对应作业；不可信代码不能在可写 Token 或发布凭据可见的环境中执行。
最后按复测证据选择：Agent 自动化有价值且交接校验可靠，就采用 Linux Agent 加 Mac CI；任务本身规则固定、没有 Agent 分析收益，就只保留普通 Mac CI；权限、产物来源或失败传播仍不清楚，就继续隔离试跑。不要因为 gh-aw CLI 能在 macOS 安装，就把它当作 Agent 作业可迁移到 Mac Runner 的证据。
如果 Agent 已稳定运行，但团队仍缺少合适的 Xcode 执行环境，下一步应核对真实环境是否满足项目工具链、访问方式和交接要求，而不是先假设任何远程 Mac 都能充当 GitHub Actions Runner。你可以先查看 MACNOX 的方案与费用信息，再根据项目是否需要持续运行、特定物理接口或稳定的长期重负载判断是否适合租用；若只是短期验证，可进一步了解 MACNOX 的 Mac 租赁方案，并在采购前自行核实实际可用的工具链与接入方式。租赁环境不能自动解决 workflow_run 的权限和提交校验问题；若你的目标是 GitHub 托管 Runner，还必须另行确认该执行环境是否支持所需的 Runner 接入能力。