自定义高级 Xcode Cloud 工作流程

♪ （定制您的高级 Xcode Cloud工作流） 欢迎观看“定制您的高级 Xcode Cloud工作流” 我是伊泰 稍后我的同事 扬也将加入进来 今年 我们推出了 Xcode Cloud Xcode Cloud是一项 内置在Xcode中的 持续集成和交付服务 专为Apple开发者设计 在其他视频中 我们介绍了如何设置 端到端工作流来持续构建 测试 和分发App 在本视频中 我们将讨论 一些更高级的功能 您可以用来 定制Xcode Cloud 以更好地满足您团队的需求 Xcode Cloud可开箱即用 旨在与Apple开发者工具 和服务进行整合 比如开发者网站 TestFlight和 App Store Connect 它还与日常使用的 各种开发工具进行整合 比如基于Git的 各种源代码管理插件 甚至是用于信息发送的Slack 不过 您可能拥有 作为流水线重要组成部分的 内部或专有工具 以及其他外部服务 在本视频中 我们将说明 如何定制Xcode Cloud 以实现与这些工具和服务的良好整合 我们将涵盖四个定制话题 首先 我们将讨论使用环境变量 将额外的信息传递到构建中 我们将学习如何利用脚本 在构建中运行的动作中 运行自定义命令 以及如何添加您在构建期间需要的 其他源代码存储库 最后是如何利用webhook 实现Xcode Cloud与 您团队使用的其他系统的整合 有很多内容要讲 让我们开门见山 从环境变量说起 当您为您的项目 进行工作流规划和配置时 有时您可能希望构建的行为 根据运行的工作流 而略有不同 例如 如果App依赖于API服务 则您可能希望您的测试使用模拟环境 而不是生产环境 在这种情况下 您可能希望将该API服务的 不同URL传递到测试中 环境变量让您可以做到这一点 它们是简单的键值对 可以让您定义一些信息 您能够利用这些信息 进一步控制构建的行为 您可以直接在工作流的环境部分中 配置您需要的任何环境变量 由于它们是工作流配置的一部分 您不必向源代码存储库提交 任何额外信息 每次工作流运行时 您定义的变量 将在运行动作的环境中被设置 对于敏感信息 比如API键或访问令牌 您可以配置一个秘密环境变量 秘密环境变量被安全处理 它们在任何时候都是 加密和安全存储的 并且它们的解密值 仅在用于运行动作的 临时环境中可用 这些值也从日志中进行编辑 您不能像查看非机密变量那样 在工作流编辑器中查看它们 让环境变量保密很容易 只需要勾选环境标量表中的 “Secret”复选框即可 然后 环境变量的值 将从视图中隐藏 一旦您保存更改 就会被安全地存储 不再可以在工作流编辑器中查看 环境变量提供了一种方便的机制 来定制行为并将额外信息传递到 您的工作流 如果与我们接下来要讲的 一项高级功能配合使用 它们将更加强大 这项高级功能就是自定义脚本 在Xcode Cloud的工作流 和Xcode的scheme之间 您可以非常灵活地设置 您希望在工作流中运行的动作 但有时 在运行动作期间 您需要运行自定义逻辑或额外命令 而自定义脚本提供了一个强大 且灵活的方法来实现这一点 自定义脚本就是您编写并包含在 源代码存储库中的shell脚本 自定义脚本在工作流中的 每个动作中运行 有三种可用的脚本类型： 克隆后脚本 Xcodebuild前脚本 和Xcodebuild后脚本 每次Xcode Cloud 运行一个动作时 它会执行一系列步骤 每个自定义脚本 正如其名称所暗示的那样 都作为步骤在动作的特定点上运行 首先 Xcode Cloud 设置一个临时环境 并从主存储库中克隆源代码 然后 Xcode Cloud 运行克隆后脚本 在解决了所有其他源依赖项后 Xcode Cloud运行 Xcodebuild前脚本 接下来 Xcode Cloud 运行动作的 相应Xcodebuild命令 Xcodebuild步骤结束后 Xcode Cloud运行 Xcodebuild后脚本 并保存之前生成的任何工件 如果工作流包括几个动作—— 例如多个构建动作—— 或者构建 测试 分析 和归档动作—— Xcode Cloud 适时为每个动作 运行自定义脚本 在Xcode Cloud 中 添加自定义脚本很简单 您只需要将带有 适当名称的shell脚本 添加到名为 “ci_scripts”的文件夹 并把该文件夹以及工作流所用 项目文件或工作区放在同级目录下 由于自定义脚本是源代码的一部分 您可以在拉取请求中 测试对脚本的修改 甚至定制它们在不同分支上的行为 Xcode Cloud 在运行动作时 会适时查看每个脚本是否存在 如果存在 就运行它们 您不需要为了运行自定义脚本 而专门对工作流进行配置 如果有脚本 它们就会被运行 请注意ci_scripts 文件夹的名称 和其中的脚本 必须完全匹配这个命名约定 以便Xcode Cloud 找到并运行脚本 您在工作流中已经配置的环境变量 可在自定义脚本中使用 包括秘密环境变量 此外 Xcode Cloud 还提供 其他各种有用的环境变量 您可以利用这些变量 向脚本添加流控制 这样就可以确保您想要运行的命令 运行在工作流中的正确点 例如 如果您想知道动作是否 在 iOS macOS tvOS或watchOS上运行 您可以使用CI_PRODUCT _PLATFORM变量的值 在更有针对性的场景中—— 也许您只希望在特定工作流的 归档动作期间运行某个命令—— 您可以在运行该命令前检查 CI_XCODEBUILD_ Action和 CI_WORKFLOW变量 是否匹配归档动作和特定的工作流 让我们看看动作中的自定义脚本 我的团队正在开发 奶昔订购App Fruta “探索Xcode Cloud 工作流”视频 介绍了如何建立工作流 以便构建 测试和分发 像Fruta这样的App 每次创建拉取请求时 我们都会使用 Xcode Cloud进行 构建和测试 我们还通过TestFlight 将来自拉取请求的构建 分发给团队成员 使他们可以在代码合并之前 验证并签署变更 今天 我想让团队成员更容易地判断 安装在他们设备上的构建 是否是来自拉取请求 为了实现这一点 当我们从拉取请求进行构建时 我们使用不同的App图标 正如您猜想的那样 使用自定义脚本使 这一切变得轻而易举 现在让我们看看怎么做

我已经在Xcode中 打开了Fruta项目 在添加自定义脚本前 我首先需要把ci_scripts 文件夹添加到我的项目 方法是在项目导航器中选择我的项目 并点击底部的加号按钮 然后选择New Group 输入文件夹名称 ci_scripts

接下来 我将把设计人员创建的 Beta版App图标集 添加到ci_scripts文件夹 这样我的自定义脚本 就可以在构建期间 把它换到相应的位置 为此 我把它从 Finder中拖到我的 ci_scripts文件夹中 在工作表中 我将取消勾选 任何选定的目标 并点击Finish

最后 让我们添加一个 Xcodebuild前脚本 该脚本将在Xcodebuild 命令之前运行 我将在适当的时候用它来把 Fruta的默认App图标集 换成Beta版App图标集 我已经创建了一个可用脚本 现在我只需要把它添加到 ci_scripts 文件夹中

我将再次取消勾选 工作表中的任何目标 并点击Finish

现在 我的脚本已经就位 让我们看看它做了什么 首先 我希望确保App图标 只有在构建来自于拉取请求时 才被换掉 我可以使用 Xcode Cloud提供的 一个环境变量 在运行时检查 构建是否为拉取请求 我可以使用与拉取请求相关的 各种环境变量 但在本例中 我将检查是否设置了 CI_PULL_REQUEST_ NUMBER环境变量

另外 我希望Beta版App图标 只用于分发到 TestFlight的构建 每当Xcode Cloud向 TestFlight分发构建时 就会首先构建项目的归档文件 检查这一点的一个好方法是验证 CI_XCODEBUILD_ ACTION环境变量的值 是否为“archive”

如果上述两个环境变量 都有预期值 那么我将使用rm和mv命令 移除现有的App图标集 用Beta版App图标集代替 请注意 我使用 CI_WORKSPACE 环境变量来为默认和 Beta版App图标集 建立正确的路径 剩下要做的就是打开一个 带有这些更改的拉取请求 等待Xcode Cloud 构建Fruta并将它 分发到TestFlight 我不是现在进行这个过程 而是提前准备了一个构建 在这里 Xcode Cloud 已经从拉取请求分支 构建并分发了Fruta 在我手机上的 TestFlight App中 我可以验证构建 是否在使用我刚刚添加的 新Beta版App图标 现在 我可以合并我的拉取请求 团队中的每个人 都会在其自有 拉取请求的构建中 看到相同的Beta版App图标 现在我们已经知道如何在Xcode Cloud中使用自定义脚本 但对于自定义脚本 还有几点需要注意 自定义脚本的标准输出和标准错误 包含在它们运行的动作日志中 也可以从Artifacts 选项卡下载它们 如果脚本没有在 您期望的时候运行 请仔细检查您是否正确命名了脚本 并将其放在与项目或工作区 处于同级目录下的 ci_scripts文件夹中 请确保添加有用的日志记录和弹性 以帮助您解决 自定义脚本中的任何问题 例如 如果脚本向外部服务 发出网络请求 您可能希望在启用 详细日志记录的情况下 包含重试这些请求的逻辑 另外 Xcode Cloud 支持脚本的退出代码 因此 如果脚本使用非零值退出 则Xcode Cloud 会把这视为错误 并放弃整个动作 您可以利用这一点 在Xcode Cloud继续执行 动作的其余部分之前 确保您需要在脚本中 运行的命令是成功的 最后应该指出的是 在测试动作中 多个环境被用来构建和运行测试 默认情况下 只有用于构建测试的环境 才会将源代码克隆到其中 运行测试的环境 不会将源代码克隆到其中 它们只有ci_scripts 文件夹可用 因此 克隆后脚本不会在这些环境中运行 自定义脚本及其所有依赖项 例如其他的shell脚本和小工具 必须完全包含在 ci_scripts文件夹中 自定义脚本和环境变量 是定制工作流行为的 两大有效工具 接下来 我的同事扬将为各位讲解 如何在Xcode Cloud中 使用额外的存储库 这样您就可以在工作流中 使用Swift包和其他依赖项 谢谢 伊泰 很多项目都是使用工具 库和框架来构建的 这些依赖项往往托管在 跨项目共享的Git存储库中 需要对它们进行检索 才能成功构建项目 Xcode Cloud自动帮助 添加这些额外的储存库 例如 我们希望添加一项新功能 好让用户可以 邀请他们的朋友并把一种饮料 分享到Fruta App 另一个团队已经实现了类似的功能 所以我们将重新使用他们的 “Invitations Kit”包 该包托管在一个 与我团队共享的 私有Git存储库中 让我们看看如何添加这个包 我在Xcode中 打开Fruta项目 从File菜单添加一个包 选择Add Package 我已经有了Nature Labs 共享的包集合 其中包含了我们组织内的 包列表 选择InvitationsKit 并点击Add Package 现在该依赖项已添加 我将从Source Control菜单中 提交这个新的依赖项 并把我的更改推送到我的分支中

我们在Xcode Cloud中 创建了一个工作流 当收到来自 任何分支的新提交时 它将开始一个新的构建 因此 这个新提交 应该启动一个新的构建 由于这是我们第一次 添加这个依赖项 我预料到这个构建将会失败 因为Xcode Cloud 无法访问 InvitationsKit 存储库 但Xcode Cloud提供了 一个简单的UI来解决这一问题 让我们前往App Store Connect中的Xcode Cloud 看看这个新的构建 不出所料 该构建失败了 Xcode Cloud显示了 一个警告横幅 表明它在访问存储库时出了问题 并向我提供了授予访问权限的选项 我接着点击Manage Repositories按钮

来到设置页面 在这里我可以将鼠标悬停在 invitationsKit 存储库链接上 然后点击Grant

您的源代码管理服务 可能会指示您 批准Xcode Cloud 访问该储存库 我接着在Github上提供了访问 InvitationsKit权限

现在 我看到 Xcode Cloud 显示Access Granted 我现在可以重新 运行那个构建了

我们预计该构建这次会成功 您可以回到Settings下的 Additional Repositories部分 找出所有已连接的 存储库 如果不再使用那些存储库 您还可以拒绝访问它们 在构建期间 Xcode Cloud将检测 新引用的存储库 当我们添加Xcode Cloud 无法访问的依赖项时 UI会提供一个快速且 简单的方法来解决这个问题 这适用于任何Git操作 包括克隆自定义脚本中的存储库 或者引用Git子模块 这也适用于所有其他的 依赖项管理工具 在本演示中 我们使用新的Swift Packages Collection功能 来包含一个额外的包 如果您希望了解更多 请观看 “利用Collections 发现和管理Swift包” 到目前为止 我们已经演示了 如何在Xcode Cloud中 定制您的构建 但有时 您和您的团队可能还希望 通过外部服务进行协作 例如 您可能希望通知 Beta测试人员 新的构建已经就绪 这就是webhook 可以发挥作用的地方 webhook为 Xcode Cloud提供了 一种与服务进行通信的途径 通过在构建生命周期的不同阶段 发送丰富的有效载荷 您可以进一步提高 工作流的自动化程度 并改善团队协作 让我们进行一个深入的了解 您可以在Xcode Cloud中 建立webhook 以便在构建的三个不同阶段 获得实时更新 首先是生成构建 要么是因为您推送了一些代码 要么是因为您手动 启动了一个构建 其次是启动构建 最后是完成构建 无论构建是成功还是失败 让我们看看如何将一个 新的webhook添加到项目中 在Xcode Cloud中很容易 就能添加webhook 点击左列的Settings选项卡 点击Webhooks 然后点击加号按钮 这时 系统会要求您 输入webhook的名称 以及App或服务的URL 该App或服务能够 接收和处理HTTP请求 然后点击Save Xcode Cloud允许您为每 个产品创建多达五个webhook 请为每个webhook提供 唯一的名称 以确保您可以轻松地识别它们 发送到端点的有效载荷 是一个JSON blob 其中包含关于 构建和产品的信息 例如App Store Connect App工作流 产品 构建等等 您需要创建一个 App或服务 来接收和处理通过 HttpRequest发送的 有效载荷 让我们来看一个示例代码 看看如何在AWS Lambda上 利用Swift来实现这一点 首先 我们接收请求 然后将其有效载荷 解码到一个JSON对象 接下来 我们检查工作流的名称 以及构建的状态 如果工作流是发布工作流 并且构建的状态是成功的 那么我们将向Twitter 发布一条消息 让测试人员 或Beta用户知道它可供测试 最后 我们将返回一个200状态码 以确认webhook请求 已被成功处理 如果您希望进一步了解 如何运行Swift无服务器函数 请观看WWDC 2020 的这段视频 如果端点没有返回成功的状态码 则Xcode Cloud将尝试 再次发送请求 Xcode Cloud还可以 方便地检查 发送到端点的 webhook内容 您可以前往App Store Connect中的Xcode Cloud 点击 设置和webhook 选择您想要检查的webhook 然后 您将会看到时间戳不同 的交付清单 选择您感兴趣的一项 系统会显示发送到服务的请求 和接收到的应答 Xcode Cloud webhook还有其他用途 这里有另外几个例子 您可以自动创建错误检查系统 或者解决该系统产生的问题 在构建失败时 向分页系统发送通知 启动下游构建 将其作为复杂发布工作流的一部分 使用webhook的丰富内容 来扩展您的工作流 这将带来无限可能 让我们复习一下本视频中所讲的内容 首先 我们讨论了 如何为您的构建 传入环境变量 然后 我们说明了如何建立脚本 来定制您的构建过程以及 如何在项目中使用额外的存储库 最后 我们讨论了如何在 构建生命周期的不同阶段 通过创建webhook 来接收Xcode Cloud 发出的回调 我们希望这些功能 可以改善您团队的日常工作流 感谢观看 ♪