Deep dive into Xcode Cloud for teams
Developer Tools 进阶 20m

深入探索 Xcode Cloud 团队协作

Deep dive into Xcode Cloud for teams

2022年6月6日

在 Apple 官方观看视频

一句话判断

如果你的团队刚开始用 Xcode Cloud，这场 Session 展示了如何通过 Webhook 和 API 将构建信息集成到现有工具链中，让 CI/CD 真正融入团队工作流。

这场 Session 讲了什么

Xcode Cloud 团队的 John 和 Jo Lynn 讲解了 Xcode Cloud 在团队场景下的进阶用法。核心内容是如何通过 Webhook 和 App Store Connect API 将 Xcode Cloud 的构建信息集成到团队的现有工具中。

Session 用一个完整的实战案例贯穿：为一个食物配送应用构建一个 Swift Server 服务，接收 Xcode Cloud 的 Webhook 回调，解析提交信息中的 issue 编号，调用 API 获取构建详情（包括构建问题），然后自动在 issue tracker 上添加评论。

还介绍了如何使用 OpenAPI Generator 从 App Store Connect API 的 OpenAPI 规范自动生成 Swift 客户端代码，以及依赖管理的最佳实践。

值得深挖的点

Webhook + API 的组合拳。 Webhook 提供实时通知（构建完成时推送），API 提供详细信息（具体构建内容、产物、问题）。两者配合才能构建完整的集成。Webhook 在 App Store Connect 的设置页面中配置 URL 即可启用。

OpenAPI Generator 自动生成 Swift 客户端。 App Store Connect API 有完整的 OpenAPI 规范。下载规范文件后，用 OpenAPI Generator 可以直接生成类型安全的 Swift 客户端包。生成的代码是 Swift Package，可以直接作为依赖引入你的服务端项目。这意味着你不需要手动处理 JSON 编解码。

构建产物的 API 管理。 通过 API 可以获取每次构建产生的所有产物的下载 URL。这让你可以将产物归档到自己的存储系统中，不依赖 Xcode Cloud 的保留策略。先从 build action 端点获取产物 ID，再调用 ci_artifact 端点获取下载链接。

Vapor 框架的快速开发体验。 Session 选择 Vapor 作为服务端框架，几行代码就完成了 Webhook 接收、JSON 解码、API 调用和 issue tracker 集成。对于 iOS 开发者来说，用熟悉的 Swift 语言写服务端逻辑降低了门槛。

代码片段

import Vapor

// 定义 Webhook 载荷结构
struct WebhookPayload: Content {
    let action: Action
    let buildRun: BuildRun
}

struct Action: Content {
    let id: String
    let isComplete: Bool
    let issues: [Issue]
}

struct BuildRun: Content {
    let id: String
    let buildNumber: String
    let sourceControl: SourceControl
}

// Vapor 路由处理 Webhook
func boot(routes: RoutesBuilder) throws {
    routes.post("webhook") { req async throws in
        let payload = try req.content.decode(WebhookPayload.self)
        
        // 只处理完成的构建
        guard payload.action.isComplete else { return HTTPStatus.ok }
        
        // 从提交信息中提取 issue 编号
        let commitMessage = payload.buildRun.sourceControl.commitMessage
        guard let issueId = extractIssueId(from: commitMessage) else {
            return HTTPStatus.ok
        }
        
        // 调用 Xcode Cloud API 获取构建问题
        let issues = try await fetchBuildIssues(
            actionId: payload.action.id
        )
        
        // 构建评论内容
        var comment = "构建 #\(payload.buildRun.buildNumber)\n"
        comment += "提交: \(commitMessage)\n"
        for issue in issues {
            comment += "- \(issue.description)\n"
        }
        
        // 发布到 issue tracker
        try await postComment(issueId: issueId, comment: comment)
        
        return HTTPStatus.ok
    }
}

最佳实践

  • 使用 Webhook 实现实时通知，配合 API 获取详细信息，构建完整的 CI/CD 集成
  • 通过 OpenAPI Generator 自动生成 API 客户端，避免手动维护 API 调用代码
  • 将构建产物通过 API 下载并归档到自有存储，不依赖 Xcode Cloud 的保留策略
  • 在提交信息中包含 issue 编号，让 Webhook 服务自动关联构建和任务
  • 认证方面，App Store Connect API 的 token 同时覆盖 Xcode Cloud API，不需要额外配置
  • 使用 Swift Package Manager 管理 API 客户端依赖，保持与项目其他依赖一致的管理方式

还有什么值得关注

  • Xcode Cloud 的 Webhook 支持自定义签名验证，确保回调的来源可信
  • 构建产物的下载 URL 有时效限制，需要在获取后及时下载
  • 如果你的团队使用 Slack 或 Teams，可以用类似方式将构建状态推送到群聊
  • 配套观看 “Customize your advanced Xcode Cloud workflows” 了解更多工作流定制选项
WWDC 2022