拓展 Xcode Cloud 工作流程

拓展 Xcode Cloud 工作流程

了解 Xcode Cloud 如何适应你的开发需求。我们会介绍如何利用启动条件、自定别名、自定脚本、网页回调以及 App Store Connect API，来简化工作流程并实现测试和分发自动化。

章节
- 0:00 - Introduction
- 1:08 - Essential Workflow Concepts
- 3:00 - Scale your workflows
- 11:38 - Connect other systems
- 12:33 - App Store Connect API
- 16:35 - Webhooks
- 20:33 - Wrap up
资源
相关视频

WWDC23
- 在 Xcode Cloud 中创建实用的工作流程
- 认识 Swift OpenAPI Generator
WWDC21
- 认识 Xcode Cloud
下载

大家好我是 Daniel 稍后我的同事 Colin 也会加入这个讲座今天我很高兴与大家探讨 Xcode Cloud 中一些强大且可扩展的功能这些功能可以扩大和扩展你的工作流程 Xcode Cloud 是 Xcode 内置的持续集成和交付服务也可在 App Store Connect 中使用它专为 Apple 开发者而设计可加快高质量 App 的开发和交付速度它汇集了多款基于云的工具可帮助你构建 App 并行运行多个自动化测试还能向测试员交付 App 以及查看和管理用户反馈从而帮助你构建更好的 App
在这个讲座中我们将探讨如何扩展 Xcode Cloud 工作流程我们首先了解一些基本的工作流程概念接下来我们将展示如何随着 App 的发展而扩大工作流程规模最后我们将扩展一个工作流程以便与 Xcode Cloud 之外的系统配合使用
让我们先看看一些基本的工作流程概念所有 Apple Developer Program 会员资格均享有每月 25 小时的构建时间你将在这个讲座中掌握必要的工具无论你是第一次使用还是想让工作流程更加灵活都会很有帮助
我们刚刚说过 Xcode Cloud 可以为你和你的开发提供很多帮助但这一切都始于一个简单的工作流程工作流程由四个元素组成即：环境、启动条件、构建操作、以及发布操作
在环境中需要为工作流程定义环境变量并决定工作流程运行时使用哪个 Xcode 和 macOS 版本你可以选择一个特定的版本也可以从一组有用的别名中进行选择例如 Latest Release (最新版本)
启动条件定义工作流程什么时候运行你可以选择对源代码控制事件作出响应例如在分支、拉取请求或 git 标签更新时你还可以选择设置时间表以便在特定的日期和时间运行工作流程或者你也可以选择手动启动条件这个条件只能手动运行
构建操作描述你希望 Xcode Cloud 对源代码执行的操作工作流程可配置一个或多个构建操作你可以选择构建 App、
运行测试、分析或归档 App 以便为分发做好准备最后发布操作定义构建操作完成运行后会发生什么你可能需要在构建完成后通过 Slack 通知你的团队或者对已归档的 App 进行一些操作如进行公证或分发到 TestFlight 等
大多数情况下只需一个简单的工作流程就能完成大量工作但工作流程很强大可以随着 App 的发展而扩大规模以满足你的需求我们最近在一款正在开发的 App 中添加了一些功能以便收集一项服务的数据我们已有一个 Xcode Cloud 工作流程当代码推送到主分支时这个流程就会启动它会构建我们的最新更改然后运行我们的测试最后通过 TestFlight 将更改交付给我们的测试员
我们的测试套件由依赖于模拟数据的单元测试和 UI 测试组成这对于测试 App 拥有的 UI 和逻辑非常有用但现在我们的 App 依赖于一项服务因此我们添加了一些与测试服务器通信的集成测试
集成测试是确保 App 与它的依赖项实现端到端协同工作的有效方法但对我们的 App 而言运行集成测试要比其他测试花费更多的时间和资源而且可能会受到 App 无法控制的网络条件等问题的影响我们希望能够配置一个工作流程来运行我们的集成测试但由于这些测试依赖于服务器并会发出真实的网络请求因此最好能进一步控制这个工作流程何时运行作为 Xcode 15.1 的一项新功能你可以使用手动启动条件将工作流程配置为手动启动我们来看看如何操作首先创建一个新的工作流程以便只运行我的新测试计划
为了节省时间我将复制现有的工作流程
在 Cloud 报告导航器中辅助点按我的 App 并选择 Manage Workflows (管理工作流程) 即可查看我的工作流程
在 Manage Workflows (管理工作流程) 视图中辅助点按现有工作流程然后选择 Duplicate (复制) 操作就会在工作流程编辑器中打开一个新的工作流程我把工作流程重命名为 Integration Tests 并将 Description (描述) 留空接下来我将添加一个手动启动条件并移除现有的条件
现在这个工作流程只有在收到我的指示时才会启动不会因任何其他事件而启动我将接受默认选项以便将启动条件与任何分支关联起来但我也可以指定一个分支、 PR 或 git 标签以便更明确地指明这个启动条件可与哪些 git 引用关联起来
我会更改测试操作来运行我的 IntegrationTests 测试计划
现在由于这个工作流程结束时不应执行任何操作因此我还要移除发布操作然后点按 Save (保存)
当然你可以将工作流程配置为使用 Environment (环境) 标签页中指定的不同版本 Xcode 和 macOS 来运行但对于这个示例而言我们希望确保两个工作流程始终使用相同的版本运行
自定别名是 Xcode 15.3 中的新功能 Xcode Cloud 已提供一些别名例如大家可能已经看到的 Latest Release (最新版本) 这些别名可确保工作流程在我们提供的最新版本上运行现在你可以为团队定义自己的别名
当你在一个或多个工作流程中使用别名时这些工作流程将使用别名中指定的 Xcode 或 macOS 版本运行这意味着更新别名时使用这个别名的所有工作流程都将使用更新后的值运行让我们在刚刚创建的新工作流程中使用这一功能
在导航器中辅助点按某一特定 App 并选择 Manage Custom Aliases (管理自定别名) 就可以看到这个 App 的所有自定别名
点按加号按钮并创建一个新的 Xcode 别名这样会弹出自定别名编辑器在这里我可以对自定别名进行命名并选择它要解析到的 Xcode 版本在这个示例中我将别名命名为 Team Preference 并选择 Xcode 15.3
点按 Save (保存) 然后对 macOS 别名执行同样的操作
为了将别名应用到我的工作流程我返回到 Manage Workflows (管理工作流程) 视图并在 Environment (环境) 标签页中打开 Integration Tests 工作流程
在 Xcode Version (Xcode 版本) 下拉菜单中现在可以看到我的自定别名选择这个别名并对 macOS 执行同样的操作
你还可以从这里的版本选择器下拉菜单或从 Integrations (集成) 菜单项中快速创建和管理自定别名最后回到第一个工作流程更新 Xcode 和 macOS 版本以使用我的新别名
完美！现在每当我在别名中更新到一个新版本时两个工作流程都会得到相应的更改
你可以在文档中进一步了解如何使用自定别名
我们的集成测试在 Xcode Cloud 中运行良好无需任何更改但我们可以让这些测试更智能一点让它们只在测试服务器在线时才运行这时我们需要利用 Xcode Cloud 的另一项强大功能即在项目中添加一个自定脚本
你可以在存储库中定义自定脚本这些脚本将在构建过程中的特定时刻运行
例如在存储库进行克隆之后、在 xcodebuild 运行之前或在 xcodebuild 运行之后
有关自定脚本的更多信息请观看 “自定义高级 Xcode Cloud 工作流程”
工作流程中定义的所有环境变量以及 Xcode Cloud 提供的环境变量均可在这些脚本中使用今天我们将在自定脚本中使用其中两个环境变量
要查看可以使用的环境变量的完整列表请访问文档中的“Environment variable reference”页面
Xcode Cloud 期望所有自定脚本都位于项目根目录下名为 ci_scripts 的文件夹中
脚本的文件名决定脚本在构建过程中的执行时间点
在这个情景中我们希望脚本在测试运行前执行
在 Xcode 中我会在项目导航器中辅助点按我的项目来创建脚本文件夹
我在文件夹中添加一个新的脚本文件并将它命名为 ci_pre_xcodebuild.sh 以便在我们的测试之前运行
我只想对集成测试执行操作因此我将添加一些逻辑来检查构建操作和 workflowID 的环境变量
在这里脚本会检查我们是否正在运行测试构建操作以及我们的工作流程是否与标识符相匹配要获取工作流程的 ID 我只需导航到 Cloud 报告导航器辅助点按工作流程并选择 Copy Workflow ID (复制工作流程 ID)
现在获得 ID 后就要回到脚本并将 ID 粘贴进去
在这个代码块中使用 curl 来调用服务器的运行状况检查端点并在失败时打印详细的错误日志
指定 set -e shell 选项后如果遇到错误这个脚本将立即退出工作流程将就此停止这正是服务器无法访问时我们所希望的
请注意由于 Xcode Cloud 构建在临时任务工作器上运行因此主机使用的 IP 地址范围会有所不同我已经在服务器防火墙的入站允许列表中添加所需的 IP 地址范围从而确保 Xcode Cloud 可以与我的服务器进行通信
要了解关于允许哪个 IP 地址的具体信息请参考“Requirements for using Xcode Cloud”文档页面我们刚刚使用手动启动条件为集成测试构建了一个新的工作流程并使用自定别名确保工作流程的 macOS 版本和 Xcode 版本保持同步我们还利用自定脚本的强大功能使测试更加智能并在测试服务器无法访问的情况下提前失败为了探索 Xcode Cloud 与其他系统连接的方式并进一步推进工作流程我将有请 Colin 来为大家讲解
谢谢 Daniel 现在我们已经了解了工作流程以及它们扩大规模的方式下面我们将以前面完成的工作为基础看看如何与 Xcode Cloud 之外的系统进行连接
正如 Daniel 刚才提到的我们的 App 现在依赖于一项服务这种新的依赖性带来了额外的风险因为有人可能会向服务器推送代码更改从而破坏我们的 App
我们可以通过运行新的 Integration Tests 工作流程来降低这种风险这将生成测试结果告诉我们 App 是否与最新的服务器更改兼容现在这个工作流程只能手动运行但我们可以使用 App Store Connect API 在测试服务器有新更改时自动启动构建
通过 App Store Connect API 可自动执行各种 App Store Connect 任务包括与 Xcode Cloud 相关的任务你可以在文档中进一步了解这些端点以及它们的调用方式
让我们回过头来看看使用 App Store Connect API 运行我们的 Integration Tests 工作流程需要什么
通过 CiBuildRuns 端点我们可以创建新的 Xcode Cloud 构建
调用这个端点时我们必须指定要运行的工作流程的标识符和要构建的 gitReference 我们知道 Integration Tests 工作流程的 ID 但不知道要构建的分支的 gitReference 我们可以使用 ScmRepositories 端点进行查找我们可以使用 repositoryID 调用这个端点以获取与这个存储库相关的所有分支、标签和拉取请求但我们首先需要知道工作流程正在使用的 repositoryID 这是 CiWorkflows 资源的一部分可使用 workflowID 进行查询
我们的脚本总共要调用三次 API 才能创建我们想要的构建
App Store Connect API 是使用 OpenAPI 指定的因此我们可以使用代码生成器为每个端点创建强类型的 Swift 代码在这个演示中我们将专注于实现但你可以在讲座 “认识 Swift OpenAPI Generator”中进一步了解我使用的开源代码生成器由于我们需要调用三次 API 来创建我们的构建为了方便起见我将在生成的 API 客户端上编写一些扩展
我们需要使用一个函数将 workflowID 作为参数获取与它关联的 CiWorkflows 资源然后返回 repositoryID
接下来我们需要通过一种方法将 repositoryID 转换成我们要构建的 gitReferenceID 这时我们可以使用 SCMRepositories 端点获取与我们的存储库相关联的所有 gitReference 然后返回具有指定名称的分支的 gitReferenceID
最后我们要开始新的构建这时我们需要 workflowID 和 gitReferenceID 并将它们传递给 ciBuildRuns 端点
现在我们总结一下首先我们用 Integration Tests 工作流程的 workflowID 调用 repoID 函数
接下来用我们要构建的分支的名称来调用 branchID 在这个示例中我将使用 main
最后我们将使用 workflowID 和 gitReferenceID 来调用 startBuild 以完成我们的脚本
请注意由 App Store Connect API 启动的构建被视为手动构建因此应确保手动启动条件的设置与要构建的引用相匹配在我们的示例中 Daniel 已经用手动启动条件设置了这个工作流程并且手动启动条件可以匹配任何分支因此我们不会遇到问题
脚本完成后我们就可以在推送新服务器代码时生成测试结果了我们可以就此打住但我们可能希望对测试结果做些什么
我们希望将目前所做的工作与生产环境连接起来这样服务器的更改在测试环境中得到验证后就可以部署了
我们可以手动检查测试结果并根据需要手动部署到生产环境但我们可以做得更好
因此我们可以利用 Xcode Cloud 的 Web 挂钩功能将测试结果连接到部署服务然后在服务器更改通过后自动推送到生产环境中
Web 挂钩允许服务在构建事件发生时做出响应因此你可以将 Xcode Cloud 集成到开发流程依赖的其他服务和工具中大家可以在文档中详细了解 Web 挂钩以及如何对它们进行配置
你只需要一个 HTTP 服务器即可侦听和响应 Web 挂钩使用 Vapor 或 Hummingbird 框架你只需几步就能通过 Swift on Server 建立一个简单的项目在这个演示中我希望重点关注实现因此我设置了一个 Vapor 服务器它包含一个可以接收 Web 挂钩的端点配置 Web 挂钩时 Xcode Cloud 将向端点发送请求其中包含 JSON 有效负载以及有关不同构建事件的详细信息
在这里我定义了一个 WebhookPayload 结构其中包含我们感兴趣的字段对于我们的方案我们需要 workflowID、buildID、构建执行进度和构建完成状态
我将使用这个结构来解码 Web 挂钩请求这样就可以轻松地从有效负载中提取字段
接下来我将添加一些逻辑用于将有效负载中的 workflowID 与 Integration Tests 工作流程的 workflowID 进行比较
有两个类似的字段可描述构建事件的状态 ExecutionProgress 描述构建是正在运行还是已经完成而 completionStatus 描述构建是成功还是失败我将更新 if 语句以对两者进行检查从而确保构建成功完成
在这个语句的正文中我将告知部署服务 Integration Tests 已通过并发送 buildID 我们的部署服务可以使用这些信息以及其他检查来批准服务器更改并部署到生产环境中
我们需要做的最后一件事是告诉 Xcode Cloud 向 Web 挂钩发送构建事件我们可以在 App Store Connect 的 Xcode Cloud 视图中完成这个操作
选中我的 App 后前往 Settings (设置) 然后点按 Webhooks (Web 挂钩) 标签页
点按加号按钮就可以配置新的 Web 挂钩
进行命名并添加侦听器的 URL
Web 挂钩设置完成后我们就万事俱备可通过 Xcode Cloud 连接服务器更改了让我们回顾一下到目前为止所做的工作
每当有新的代码更改部署到服务的测试环境时我们都会调用 App Store Connect API 来启动 Integration Tests 工作流程的构建这将运行测试来验证 App 与测试服务器之间的集成
我们的 Web 挂钩侦听器会处理测试结果如果所有测试都通过就会将更改部署到生产环境中
在所有测试都通过的情况下我们的管道就实现了从代码推送到生产部署的完全自动化
但是如果推送的服务器更改导致 App 出现问题
集成测试就会失败 Web 挂钩侦听器会阻止将更改部署到生产环境中这正是我们想要的结果
我们讨论的是服务器代码更改但推送更改的团队成员可能甚至没有在他们的机器上安装 Xcode 好消息是由于 Xcode Cloud 已集成到 App Store Connect 中他们仍然可以通过浏览器查看和调查问题
这是来自 App Store Connect 的构建结果其中运行情况与预期不符从 Actions (操作) 部分可以看出我们的 IntegrationTests 操作明显出现问题
点按 Tests (测试) 部分将打开测试报告
即使我在 App Store Connect 中我也可以看到并完成 Xcode 中的所有操作我可以按测试状态进行筛选按测试套件进行搜索还能查看每个测试的详细信息在这个示例中我可以看到服务器返回的数据有问题
如果我需要进一步调查我可以点按边栏中的 Artifacts (工件) 以下载与构建相关的各种文件如 Xcode 日志和崩溃报告我们在这个讲座中介绍了很多内容但这些只是 Xcode Cloud 工作流程众多扩展方式中的少数几个
我们使用手动启动条件、自定别名和自定脚本来扩大我们团队的工作流程并使用 App Store Connect API 和 Web 挂钩将它们集成到其他系统中
请观看我们的其他讲座例如 “在 Xcode Cloud 中创建实用的工作流程” 和“认识 Xcode Cloud” 了解 Xcode Cloud 如何增强团队的 CI 流程
我们希望大家能从中获得一些启发以便将这些概念应用到你们自己的工作流程中感谢观看

#!/bin/sh

set -e

if [[ $CI_XCODEBUILD_ACTION == "test-without-building" && $CI_WORKFLOW_ID == "82D89C93-B69C-46B5-A794-A2BCFD3EE487" ]]
then
    curl https://example.com/health --fail
fi

14:01 - App Store Connect API - Client Extension

extension Client {
    func repoID(workflowID: String) async throws -> String {
        return try await ciWorkflowsGetInstance(
            path: .init(id: workflowID),
            query: .init(include: [.repository])
        ).ok.body.json.data.relationships!.repository!.data!.id
    }
    
    func branchID(repoID: String, name: String) async throws -> String {
        return try await scmRepositoriesGitReferencesGetToManyRelated(
            path: .init(id: repoID)
        )
        .ok.body.json.data
        .filter { $0.attributes!.kind == .BRANCH && $0.attributes!.name == name }
        .first!.id
    }
    
    func startBuild(workflowID: String, gitReferenceID: String) async throws {
        _ = try await ciBuildRunsCreateInstance(
            body: .json(.init(
                data: .init(
                    _type: .ciBuildRuns,
                    relationships: .init(
                        workflow: .init(data: .init(
                            _type: .ciWorkflows,
                            id: workflowID
                        )),
                        sourceBranchOrTag: .init(data: .init(
                            _type: .scmGitReferences,
                            id: gitReferenceID
                        ))
                    )
                )
            ))
        ).created
    }
}

14:43 - App Store Connect API - Main Function

static func main() async throws {
    let client = try Client(
        serverURL: Servers.server1(),
        configuration: .init(dateTranscoder: .iso8601WithFractionalSeconds),
        transport: URLSessionTransport(),
        middlewares: [AuthMiddleware(token: ProcessInfo.processInfo.environment["TOKEN"]!)]
    )
    
    let workflowID = "82D89C93-B69C-46B5-A794-A2BCFD3EE487"
    let repoID = try await client.repoID(workflowID: workflowID)
    
    let branchName = "main"
    let branchID = try await client.branchID(repoID: repoID, name: branchName)
    
    try await client.startBuild(workflowID: workflowID, gitReferenceID: branchID)
}

17:09 - Webhook Handler Implementation

struct WebhookPayload: Content {
    let ciWorkflow: CiWorkflow
    let ciBuildRun: CiBuildRun
    
    struct CiWorkflow: Content {
        let id: String
    }
    
    struct CiBuildRun: Content {
        let id: String
        let executionProgress: String
        let completionStatus: String
    }
}

func routes(_ app: Application) throws {
    let deploymentService = ExampleDeploymentClient()
    let workflowID = "82D89C93-B69C-46B5-A794-A2BCFD3EE487"
    
    app.post("webhook") { req async throws -> HTTPStatus in
        
        return HTTPStatus.ok
    }
}

正在查找特定内容？在上方输入一个主题，就能直接跳转到相应的精彩内容。

提交你查询的内容时出现错误。请检查互联网连接，然后再试一次。

章节

资源

相关视频

WWDC23

WWDC21