Buildkite 企业 iOS CI 怎么接入 Mac？2026 指南

Buildkite 企业 iOS CI 接入 Mac 时，应由 Buildkite 编排流水线、Mac Agent 执行依赖 Xcode 的构建与测试；Linux 能完成的步骤按实际依赖留在 Linux。队列负责路由，不等于主机隔离；生产签名与不受信任代码必须另设信任边界。

正在迁移 iOS 流水线的平台工程师：需要设计路由并验收构建结果。
维护企业 Mac 构建节点的 IT 负责人：需要核对运行账号、启动方式和维护责任。
负责发布与安全治理的团队负责人：需要区分测试任务、签名凭证与不受信任代码。

[ SECTION_01 ] 第一阶段：先划清 Buildkite 企业 iOS CI 接入边界

先把现有流水线拆成两类，而不是把所有步骤统统搬到 Mac：

• 适合留在 Linux 的步骤：不调用 Apple 工具、不依赖 macOS 文件系统或环境的静态检查、部分代码质量扫描，以及可在现有 Linux 环境完成的依赖处理。
• 应路由到 Mac 的步骤：需要 Xcode 编译器或 SDK 的构建、iOS 模拟器测试，以及需要 Apple 平台工具链的归档和签名流程。
• 按项目验证的步骤：源码检出、缓存、产物上传等环节，运行平台未必固定。重点是检查脚本、依赖和权限，而不是凭步骤名称决定运行节点。

Buildkite Agent 会连接 Buildkite 并轮询任务；自托管 Agent 在团队自己的机器上执行被分配的命令。先阅读 Buildkite Agent 的工作方式与任务路由说明，再依据 Apple 的 Xcode 命令行工具设置文档确认哪些命令依赖实际安装的 Xcode。

Buildkite Mac Agent 怎么接入企业 iOS 项目？
在 Buildkite 中为自托管 Mac Agent 配置对应集群和队列，再让项目中需要 Apple 工具链的步骤匹配该队列。Agent 完成注册并接到任务后，还要核对实际日志、检出权限和工具链选择；队列名称本身不能证明这些条件都正确。

[ SECTION_02 ] 第二阶段：准备主机、macOS 账号与 Agent 身份

安装前，建立一份主机清单。记录 macOS 版本、芯片架构、安装的 Xcode 及 Command Line Tools、工作目录位置，并明确谁负责系统和工具链更新。自托管 Agent 的基础设施与维护由组织负责，不能把软件装好等同于运维交接完成。Buildkite macOS 安装文档说明了安装与运行方式，也应作为核对安装步骤的依据。

自托管 Mac Agent 应由哪个 macOS 用户运行？
应选由企业管理、仅获构建所需权限的专用账号，并用实际任务确认它能读写工作目录、访问所需工具和导出构建产物。若任务涉及钥匙串或图形界面测试，还应在该账号的真实运行上下文中检查访问行为。不要默认管理员账号最省事就最合适，也不要把个人开发者账号作为无人维护的服务身份。

同时区分两种凭证：

• Agent Token：用于 Agent 向对应集群注册。按 Buildkite Agent Token 说明管理存储、授权和轮换；不要把令牌写进仓库、流水线脚本或可公开读取的日志。
• 仓库访问凭证：用于检出源码，权限应限于构建需要的仓库和操作。不要因为 Agent 已获准注册，就默认它应持有生产发布凭证或广泛的仓库访问权限。

[ SECTION_03 ] 第三阶段：安装 Agent，并验证持续运行

按团队选定的安装方式部署，并以官方当前文档核实命令和配置位置。Buildkite 的 macOS 安装文档提供 Homebrew 安装示例：

brew install buildkite/buildkite/buildkite-agent

配置凭证时，用受控的环境变量或团队认可的密钥管理方式注入，不要将真实 Token 写进命令历史、配置仓库或排障截图。安装完成后，先在受控终端启动 Agent，确认它成功注册、状态正常，再安排长期运行。

临时从终端启动，只能证明当前会话能运行 Agent；它不能证明登出或重启后服务仍会恢复。若采用 launchd，要确认服务配置、文件路径和权限适合指定 macOS 用户，并在远程重启后检查 Agent 是否重新注册、是否能接单、日志是否可读。实际部署方式还应和团队的登录、图形会话及维护策略一起核验。

⚠️ 不要只看进程是否存在。Agent 进程活着但未注册、令牌失效、路径权限不符或无法领取任务，都不能算持续运行已验收。

[ SECTION_04 ] 第四阶段：用队列和任务规则路由构建工作

为 macOS 构建节点配置有明确用途的队列或任务匹配规则。在流水线中，让需要 Xcode 的步骤显式请求 Mac 队列；平台无关的检查仍路由到适合的执行环境。Buildkite 的队列管理文档介绍了队列如何组织集群中的 Agent。

概念上，步骤可写成如下形式，队列名应替换为团队实际配置：

steps:
  - label: "iOS build and test"
    command: "xcodebuild -scheme App -destination 'generic/platform=iOS Simulator' build test"
    agents:
      queue: "macos-ios"

这只是路由示意，不是对项目 Scheme、目标设备或测试参数的通用保证。应检查构建日志中的 Agent 身份与工作目录，再确认命令实际运行在预期主机上。仅凭队列名或 Agent 标签，不能推断 macOS 版本、Xcode 版本、隔离级别或凭证状态。

[ SECTION_05 ] 第五阶段：把队列路由与安全隔离分开治理

队列能否隔离 iOS 测试和生产签名任务？
队列可以帮助把任务路由到不同 Agent，但队列本身不构成主机级安全边界。Buildkite 的安全检查清单区分队列路由与集群隔离；因此，若测试代码不可信、生产任务需要签名材料，仅改队列名称不足以证明隔离成立。应结合集群、主机、凭证授权、网络访问和团队审批策略评估。

按信任级别分别处理：

• 常规构建与测试：只提供检出、依赖下载和测试所需权限，检查构建脚本及插件的来源与变更审批。
• 不受信任的拉取请求：不要让其执行环境能读取生产签名身份或发布凭证。必要时采用独立主机及适当的集群边界，并限制可访问的密钥和网络资源。
• 生产签名与发布：把签名材料限定在经过审批的任务和执行环境中。检查私钥、钥匙串访问、发布授权及日志脱敏责任分别由谁承担。

安全策略还应明确 Agent 能访问哪些项目、秘密和内部网络，并把这些权限与代码信任级别对应起来。队列能帮助路由任务，却不能替代主机隔离、凭证范围限制或审批流程。

[ SECTION_06 ] 第六阶段：用真实流水线完成验收

接入验收要覆盖一次团队真实的 iOS 工作流，而不是只看任务能否启动。按项目条件选择代表性提交，依次检查源码检出、Agent 身份、Xcode 选择、构建与测试、产物留存，以及适用时的归档和签名流程。

如何确认 Mac Agent 调用的是预期 Xcode？
在该步骤的运行环境中记录 xcode-select --print-path 和 xcodebuild -version 输出，并与项目批准的工具链清单比对。Apple 文档说明 xcode-select --print-path 可显示当前命令行工具使用的开发者目录；如果需要临时指定另一套工具链，可在符合权限和项目要求时用 DEVELOPER_DIR 覆盖。验收应确认运行结果，而不是仅查看主机上安装了哪些 Xcode。具体设置方式可核对 Apple 的 Xcode 命令行工具文档。

对测试步骤，保存退出状态、可读日志及测试结果。Apple 说明通过 xcodebuild 运行测试会生成 .xcresult 测试结果包，其中可包含测试会话结果、代码覆盖信息（如已启用）和相关日志；把结果包与构建产物按团队保留策略归档，便于后续复核。参见 Apple 关于运行测试与解读结果的文档。

按条件决定是否放行

• 若项目构建和测试都必须调用 Xcode，且 Agent 用户在重启后可以稳定恢复服务，则将 Apple 专属步骤路由到 Mac。
• 若某个步骤不依赖 macOS 或 Apple 工具链，则保留在现有通用执行环境；先检查脚本与依赖，不为“统一环境”强制迁移。
• 若不受信任的代码可以读取生产签名材料，则先撤销或收紧凭证授权，再评估主机、集群及审批边界；不能以队列分开作为放行依据。
• 若日志不能证明 Agent 身份、工具链选择、测试结果和产物留存，则不应仅凭队列在线或任务已启动判定接入完成。

下表用于评审承载方式，不以未经核实的价格或主机性能替代验收。自建与远程承载的具体交付、访问方式和运维责任，应以实际合同及服务资料为准。

接入后的选择取决于团队是否需要长期固定负载、物理设备或自主管控：这类需求通常更适合评估自购与自运维。现有机器若出现资源闲置、扩容需要重新采购、更新和故障都压在内部团队等问题，而项目又需要临时构建节点，可以把远程 Mac 纳入承载评估。通过 NOVAKVM 服务入口了解相关方案时，应逐项核实可用配置、租赁周期、地域、交付和访问责任；也可以参考远程 Mac 采购与选型页面，再结合企业自身的运维边界判断是否适合。未核实这些信息前，不宜把它们当成已满足的 CI 能力。