Xcode Cloudワークフローの拡張

Xcode Cloudワークフローの拡張

Xcode Cloudをそれぞれの開発ニーズに適応させる方法を確認しましょう。開始条件、カスタムエイリアス、カスタムスクリプト、Webhook、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
- Swift OpenAPI Generatorの紹介
- Xcode Cloudでの実用的ワークフロー作成
WWDC21
- Xcode Cloudについて
こんにちは Danielです後半ではColinにも参加してもらいますここでは Xcode Cloudのパワフルで拡張性に優れた機能について説明しますこれらの機能はワークフローのスケーリングと拡張に役立ちます Xcode CloudはXcodeに組み込まれた継続的インテグレーションおよびデリバリサービスであり App Store Connectでも利用できます Appleデベロッパ向けに設計されたもので高品質なアプリの開発と提供を加速させますアプリのビルド並列での自動テストの実行テスターへのアプリの配信優れたアプリの開発に役立つユーザーフィードバックの確認と管理をサポートする様々なクラウドベースのツールが用意されています
このセッションでは Xcode Cloudワークフローの拡張方法について説明しますまずワークフローの基本的な概念を確認します次にアプリの成長に応じてワークフローのスケーリングを行う方法を紹介します最後に Xcode Cloud以外のシステムと連携できるようにワークフローを拡張します
ではワークフローの基本的な概念を確認することから始めましょう全てのApple Developer Programメンバーシップは月25時間のビルド時間を提供しますこのセッションでは Xcode Cloudを初めて使用する方もワークフローの柔軟性を高めたい方も有益な情報が得られます
先ほど触れたように Xcode Cloudには皆さんの開発作業に役立つ様々な機能がありますがすべての出発点はシンプルなワークフローですワークフローは4つの要素で構成されます環境開始条件ビルドアクションポストアクションです
環境ではワークフローの環境変数を定義しますここではワークフローの実行時に使用するXcodeと macOSのバージョンも指定します特定のバージョンを選択することも最新リリースなどのエイリアスから選ぶこともできます
開始条件ではワークフローを実行するタイミングを指定しますブランチプルリクエスト Gitタグのアップデートなどソースコントロールイベントへの対応を選択できますスケジュールを設定して特定の日時にワークフローを実行することもできますまたは手動開始条件を選択すると手動でのみ実行することができます
ビルドアクションではソースコードに対して Xcode Cloudで何を行うかを記述しますワークフローに1つ以上のアクションを設定できますアプリのビルド
テストの実行分析またはアーカイブを選択しアプリの配信に向けて準備できます最後にポストアクションではビルドアクションの実行完了後の処理を定義しますビルド完了時にSlackでチームに通知する場合やアーカイブ済みアプリを公証したり TestFlightへ配信したりする場合などが考えられます
大抵の場合はシンプルなワークフローだけで多くのことができますしかしワークフローはパワフルですアプリの成長に応じてニーズに合わせたスケーリングが可能です私たちは最近開発中のアプリに機能を追加してサービスからデータを取得できるようにしました既存のXcode Cloudワークフローはコードがメインブランチにプッシュされた時に開始されます最新の変更をビルドした後テストを実行し最後に TestFlightのテスターに変更が送信されます
このテストスイートはユニットとUIのテストで構成されモックデータを使用しますアプリのUIとロジックを実際に試すのに適していますしかしこのアプリにはサービスへの依存関係があるためテストサーバとやり取りする統合テストをいくつか追加しました
統合テストは依存関係を持つアプリが全体として正常に機能することを確認するのに役立ちますただしこの統合テストを実行するにはより多くの時間とリソースが必要になりネットワーク状態などアプリで制御できない問題の影響を受ける可能性があります統合テストを実行するワークフローを設定できるようにしたいのですがサーバに依存し実際のネットワークリクエストを行うためこのワークフローを実行するタイミングをより細かく制御できると便利です Xcode 15.1の新機能である手動開始条件を使用するとワークフローを手動で開始するように設定できますその方法を見てみましょうまず新しいテストプランを実行するだけの新しいワークフローを作成します
時間を節約するため既存のワークフローを複製します
ワークフローを表示するには Cloudのレポートナビゲータでアプリを副ボタンでクリックしを選択します
ビューで既存のワークフローを副ボタンでクリックしアクションを選択しますワークフローエディタに新しいワークフローが表示されますこのワークフローの名前を「Integration Tests」に変更しは空白のままにします次に条件として追加し既存の条件を削除します
これでこのワークフローは手動で指定した時だけ開始され他のイベントでは開始されませんデフォルトのオプションをそのまま使用すると開始条件がすべてのブランチと関連付けられますただしブランチ PR またはGitタグを選択してこの開始条件を関連付けるGit参照を具体的に指定することもできます
アクションを変更して IntegrationTestsテストプランを
現時点ではこのワークフローの終了時に何も実行する必要がないためポストアクションを削除してをクリックします
もちろんタブで指定された様々なバージョンのXcodeや macOSを使用してワークフローを実行するよう設定できますただし今回はどちらのワークフローも必ず同じバージョンを使用して実行する必要があります
カスタムエイリアスは Xcode 15.3の新機能です Xcode Cloudの現行リリースにも既にいくつかエイリアスがあり利用可能な最新バージョンでワークフローを実行するように指定できますさらに今回はチーム独自のエイリアスを定義できるようになりました
1つ以上のワークフローでエイリアスを使用するとそれらのワークフローはそのエイリアスで指定されたバージョンの XcodeまたはmacOSで実行されますつまりエイリアスを更新した場合そのエイリアスを使用しているすべてのワークフローが更新後の値で実行されます先ほど作成した新しいワークフローでこの機能を使ってみましょう
特定のアプリのカスタムエイリアスをすべて表示するにはナビゲータでアプリを副ボタンでクリックしを選択します
新しいXcodeエイリアスを作成するためボタンをクリックしますカスタムエイリアスエディタが表示されますここにカスタムエイリアスの名前を入力しそれに対応させるXcodeのバージョンを選択しますここでは「Team Preference」と名付け Xcode 15.3を選択します
をクリックし macOSのエイリアスについても同様に設定します
このエイリアスをワークフローで使用するにはビューに戻ってワークフローを開きタブを表示します
Xcodeバージョンのドロップダウンに作成したカスタムエイリアスが表示されますこれを選択し macOSについても同様にします
カスタムエイリアスの作成と管理はこの画面のバージョン選択ドロップダウンまたはメニューのからでも簡単に行えます最後に最初のワークフローに戻り新しいエイリアスで使用する XcodeとmacOSのバージョンを更新します
できましたこれでエイリアスのバージョンを新しく更新するたびに両方のワークフローにその変更が適用されます
カスタムエイリアスの使い方についてはこちらのドキュメントをご覧ください
この統合テストはXcode Cloudで機能し変更の必要はありませんがテストサーバがオンラインの場合にのみ実行されるようにするとさらにスマートになりますそれには Xcode Cloudのもう1つの優れた機能を活用してプロジェクトにカスタムスクリプトを追加します
リポジトリ内でカスタムスクリプトを定義してビルドの特定のタイミングで実行することができます
リポジトリのクローンの作成後 xcodebuildの実行前または実行後のいずれかのタイミングです
カスタムスクリプトの詳細については「Customize your advanced Xcode Cloud workflows」をご覧ください
ワークフローで定義されているすべての環境変数に加え Xcode Cloudで用意されている環境変数もスクリプトで使用できます今日はそのうちの2つをカスタムスクリプトで使用します
使用可能な環境変数の一覧はドキュメントの「Environment variable reference」ページをご覧ください
Xcode Cloudではすべてのカスタムスクリプトをプロジェクトのルートのci_scriptsフォルダに格納する必要があります
スクリプトのファイル名によってビルドのどのタイミングで実行されるかが決まります
このシナリオではテストの実行直前にスクリプトを実行します
Xcodeのプロジェクトナビゲータでプロジェクトを副ボタンでクリックしてスクリプトのフォルダを作成します
このフォルダに新しいスクリプトファイルを追加し ci_pre_xcodebuild.shという名前を付けてテストの前に実行されるようにします
統合テストのためのアクションのみを実行したいのでビルドアクションとworkflowIDの環境変数をチェックするロジックを追加します
ここでスクリプトチェックを行いテストのビルトアクションを実行することワークフローとIDが一致することを確認しますワークフローのIDを取得するには Cloudのレポートナビゲータに移動してワークフローを副ボタンでクリックしを選択します
IDをコピーしたらスクリプトに戻ってペーストします
このブロック内で curlを使用してサーバの健全性チェックエンドポイントを呼び出しエラー発生時には詳細なエラーログを出力します
set -e shellオプションを指定するとエラーの発生時にこのスクリプトはただちに終了しワークフローはそこで停止しますサーバに到達不能な場合はこのような対応が必要です
Xcode Cloudのビルドは一時的なタスクワーカーで実行されるためホストが使用する IPアドレスの範囲は様々です Xcode Cloudとサーバが通信できるようにするためここでは必要なIPアドレス範囲をサーバのファイアウォールのインバウンド許可リストに追加しています
許可するIPアドレスの詳細についてはドキュメントの「Requirements for using Xcode Cloud」ページをご覧くださいここでは手動開始条件を使用して統合テスト用の新しいワークフローを構築しましたまたカスタムエイリアスを使用しすべてのワークフローでmacOSと Xcodeのバージョンを一致させましたさらにカスタムスクリプトを活用してテストを少しスマートにしテストサーバに到達不能な場合は早期にエラーになるようにしました Xcode Cloudと他のシステムを連携させてワークフローをさらに強化する方法については Colinに説明してもらいます
Daniel ありがとうワークフローとそのスケーリング方法について理解したところで次は Xcode Cloud以外のシステムと接続する方法を見ていきましょう
Danielが説明したようにこのアプリはサービスに依存していますこの新しい依存関係にはリスクが伴います誰かがコード変更をサーバにプッシュするとアプリに問題が生じるためです
このリスクを軽減するには新しいIntegration Tests ワークフローを実行しますこのワークフローで生成されるテスト結果によりアプリが最新のサーバ変更に対応しているかどうか確認できます現時点ではこのワークフローは手動でのみ実行されますが App Store Connect APIを使用するとテストサーバが変更されるたびにビルドを自動的に開始できます
App Store Connect APIにより Xcode Cloudに関連するタスクを含め App Store Connecの様々なタスクを自動化できますこれらのエンドポイントの詳細とその呼び出し方法についてはドキュメントをご覧ください
App Store Connect APIを使用して Integration Testsワークフローを実行するには何が必要かを逆算で考えてみましょう
CiBuildRunsエンドポイントにより新しいXcode Cloudのビルドを作成できます
この呼び出しでは実行するワークフローの識別子とビルドするgitReferenceを指定する必要があります Integration Testsワークフローの IDはわかっていますがビルドするブランチの gitReferenceofはわかりませんこれを確認するには ScmRepositoriesエンドポイントを使用します repositoryIDを使用してこのエンドポイントを呼び出すことでそのリポジトリに関連付けられているすべてのブランチタグプルリクエストを取得できますしかしまずワークフローで使用されている repositoryIDを知る必要がありますこれはCiWorkflowsリソースに含まれており workflowIDを使って照会できます
このスクリプトでは合計3つのAPI呼び出しを行って必要なビルドを作成します
OpenAPIを使用して App Store Connect APIを指定しコードジェネレータを使って各エンドポイントの厳密に型指定された Swiftコードを作成できるようにしますこのデモでは実装に重点を置いていますここで使用するオープンソースのコードジェネレーターの詳細については「Meet Swift OpenAPI Generator」をご覧くださいビルドを作成するには 3つのAPI呼び出しが必要になるため便宜上生成された APIクライアントで拡張を記述します
ここで必要なのは workflowIDを引数に取り関連付けられた CiWorkflowsリソースを取得し repositoryIDを返す関数です
次に必要なのはこのrepositoryIDをビルドするgitReferenceIDに変換する方法ですこれを行うには SCMRepositories エンドポイントを使用しますがそれにはリポジトリに関連付けられたすべてのgitReferencesをフェッチして指定した名前を持つブランチの gitReferenceIDを返します
最後に新しいビルドを開始しますそのために必要なのは workflowIDとgitReferenceIDでこれらを ciBuildRunsエンドポイントに渡します
それでは改めて見ていきましょうまず repoID関数を呼び出しますがここでIntegration Testsワークフローの workflowIDを指定します
次にビルドするブランチの名前を指定して branchIDを呼び出しますここでは「main」を使用します
最後に workflowIDとgitReferenceIDを使用してstartBuildを呼び出してスクリプトは完成です
ただし App Store Connect APIで開始されるビルドは手動と見なされるためビルドする参照に対応する手動開始条件を設定しておく必要があります今回は Danielが既にあらゆるブランチに対応する手動開始条件をこのワークフローに設定しているので問題はありません
これでスクリプトが完成し新しいサーバコードがプッシュされるたびにテスト結果を生成できるようになりましたここで終了でもよいのですがテスト結果に少し手を加えましょう
ここまでの成果をプロダクション環境に接続してテスト環境での検証後にサーバの変更がデプロイされるようにしたいと思います
テスト結果を手作業でチェックしプロダクション環境に手動でデプロイすることもできますがもっと良い方法があります
Xcode CloudのWebhook機能を利用するとテスト結果をデプロイメントサービスに接続しテストに合格したサーバの変更を自動的にプロダクション環境にプッシュできます
Webhookによりビルドイベントの発生時にサービスを対応させることができますそのため開発プロセスで利用している他のサービスやツールに Xcode Cloudを統合できます Webhookの詳細と設定方法についてはドキュメントをご覧ください
Webhookを検知して対応する必要があるのは HTTPサーバのみです Swift on Serverを使用するとシンプルなプロジェクトを数ステップで作成できますそれにはVaporまたは Hummingbirdフレームワークを使用しますこのデモでは実装に焦点を当てるため Webhookを受信できるエンドポイントを持つ Vaporサーバが既にセットアップされています Webhookを設定すると Xcode Cloudはエンドポイントにリクエストを送信しますこれは様々なビルドイベントに関する詳細情報を含むJSONペイロードで構成されます
ここでは WebhookPayload構造体を定義し対象となるフィールドを含めていますこのシナリオで必要なのはワークフローID ビルドID ビルドの実行状況ビルドの完了状態です
この構造体を使用して Webhookリクエストをデコードすることで簡単にペイロードからフィールドを抽出できます
次にペイロードのワークフローIDと Integration TestsワークフローのワークフローIDを比較するためのロジックを追加します
類似したフィールドが2つありますこれらはビルドイベントの状態を示しています ExecutionProgressはビルドが実行中か完了したかを示します一方 completionStatusはビルドが成功したかどうかを示します if文を更新して両方のチェックを行いビルドが正常に完了していることを確認します
この文のボディでは統合テストに合格したことをデプロイメントサービスに通知し buildIDを送信しますこのデプロイメントサービスでは他のチェックと共にこの情報を使用することでサーバの変更を承認してプロダクション環境にデプロイします
最後にビルドイベントを Webhookに送信するよう Xcode Cloudに指示しますこれは App Store Connectの Xcode Cloudビューから行うことができます
アプリを選択した状態でを開きタブをクリックします
新しいWebhookを設定するためボタンをクリックします
名前を入力しリスナーのURLを追加します
Webhookを設定したら Xcode Cloudを介してサーバの変更を接続するための準備は完了ですここまでの作業を振り返りましょう
新しいコード変更がサービスのテスト環境にデプロイされるたびに App Store Connect APIを呼び出して Integration Testsワークフローのビルドを開始しますこれによりアプリとテストサーバの連携を検証するテストが実行されます
結果はWebhookリスナーによって処理されすべてのテストに合格すると変更がプロダクション環境にデプロイされます
すべてが合格の場合コードのプッシュからプロダクション環境へのデプロイまでパイプラインが完全に自動化されます
しかしアプリで問題が生じるようなサーバ変更がプッシュされた場合は
統合テストに不合格となり Webhookリスナーによってプロダクション環境への変更のデプロイが中止されますこれが私たちの求める動作です
ここで取り上げているのはサーバのコード変更なので変更をプッシュしたチームメンバーが自分のマシンにXcodeをインストールしていない可能性がありますしかし Xcode Cloudは App Store Connectに組み込まれているためその場合でも各自のブラウザで問題の確認と調査を行えます
こちらは想定どおりに実行できなかった場合の App Store Connectのビルドの結果ですセクションを見ると IntegrationTestsアクションに問題があったことがわかります
セクションをクリックするとテストレポートが開きます
App Store Connectからでも Xcodeを開いているかのように確認などの操作を行えますテストステータスでフィルタリングしたりテストスイートで検索したり各テストの詳細情報を表示したりできますここではサーバから返されたデータに問題があったことがわかります
さらに詳しい調査が必要な場合はサイドバーのをクリックして Xcodeのログやクラッシュレポートなどビルドに関連する様々なファイルをダウンロードできますこのセッションでは様々なことを取り上げましたが Xcode Cloudでワークフローを拡張する方法のほんの一部に過ぎません
ここでは手動開始条件カスタムエイリアスカスタムスクリプトを使用してチームのワークフローを拡張し App Store Connect APIと Webhookを使って他のシステムに統合しました
「Create practical workflows in Xcode Cloud」や「Meet 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