高度なXcode Cloudワークフローのカスタマイズ

♪ （高度なXcode Cloudワークフローの カスタマイズ） 「高度なXcode Cloudワークフローの カスタマイズ」 へようこそ 板井と申します後ほど同僚のYanも 参加します 今年はXcode Cloud について紹介したいと思います Xcode Cloudは継続的 インテグレーション・デリバリー サービスでXcodeに内蔵されています これはAppleの開発者専用に開発されています 他のセッションではエンドツーエンドの ワークフローのセットアップを行い 連続的にAppのビルド テスト ディストリビューションを行う 方法を説明しています このセッションではXcode Cloudをカスタマイズして チームのニーズにマッチさせる ために使用できるいくつかの 高度な機能を紹介します Xcode Cloudは開発者のウェブサイト TestFlight Apple Store Connect などの Apple開発者ツール・ サービスと統合するように 設計されています 箱から取り出してすぐに使用 できるようになっています 全ての大手のGitベースのソース コントロールプロバイダのような 日々使われる重要な開発ツールだけでなく メッセージング用の Slackとも統合します しかし 自前の独自仕様のツールや 他の外部サービスも利用していて パイプラインの重要な部分に 使用されているかもしれません このセッションではXcode Cloudをカスタマイズして これらのツールやサービスと適切に統合する方法を 説明します 4つのカスタマイゼーションの トピックスを説明します まず環境変数を使用して 情報の追加ビットをビルドに 受け渡すことについて話そうと思います スクリプトを使用して ビルドで実行したアクションで カスタムコマンドを実行する方法について学びます また ビルド中に必要な他のソース リポジトリを追加する方法に ついても学びます そして最後にWebhookを 使用してXcode Cloudを チームが使用する他のシステムと 統合する方法を学びます 説明するものはかなり多いです ですから早速環境変数の説明に入ります プロジェクトに対してワークフローを計画し 構成するに伴い実行しているワークフローに応じて ビルドの動作を少し 変えたいことがあるかもしれません 例えばAppがAPIサービスに依存している場合 テストで本番環境ではなく ステージング環境を使用したいと 思うかもしれません この場合はテストにAPIサービス に対する別のURLを受け渡す方がよいでしょう 環境変数を利用するとこれを行うことができます これはシンプルなキー/値ペアで これを利用するとビルドの動作を 更に制御するために使用できる情報を いくつか定義できます 必要な環境変数はワークフローの セクションで構成できます これらはワークフローの構成の一部であるため ソースリポジトリに追加情報を コミットする必要はありません ワークフローが実行される度に 定義した変数がアクションを 実行している環境で設定されます APIキーやアクセストークンなど 機密性の高い情報の場合は 秘密環境変数を構成できます 秘密環境変数は安全に処理されます 常に暗号化され安全に保存され 解読された値は アクションを実行するために 使用される一時環境のみで利用されます また値はログから編集され 非秘密変数とは違って ワークフローエディタでは表示できません 環境変数を秘密にするのは簡単です 環境変数テーブルで チェックボックスを選択するだけです 環境変数の値はビューで非表示になり 変更を保存すると 安全に保存され ワークフローエディタでは表示できなくなります 環境変数は動作をカスタマイズし 追加情報をワークフローに 受け渡すための手軽なメカニズムを提供します 高度な機能であるカスタムスクリプトと 組み合わされると よりパワフルになります Xcode Cloudの ワークフローとXcodeの スキームの間でワークフローで 実行するアクションを セットアップする方法において 高い柔軟性を確保できるのです しかしアクション中にカスタム ロジックや追加のコマンドを 実行する必要がある場合もあります そしてこれを達成するためにカスタムスクリプトは パワフルで柔軟性の高い方法を提供します カスタムスクリプトはユーザが書く シェルスクリプトで ソースリポジトリに含まれています カスタムスクリプトは ワークフローの各アクションで 実行されます 利用できる3つのタイプのスクリプトがあります ポストクローンスクリプト プレ Xcodebuildスクリプト ポストXcodebuildスクリプトです Xcode Cloudは アクションを実行する度に 一連のステップを実行します 名前がヒントになっている各カスタムスクリプトは アクションの特定ポイントで ステップとして実行されます まずXcode Cloudは 一時環境でセットアップされ プライマリリポジトリのソースコードを複製します その後 Xcode Cloudはポスト クローンスクリプトを実行します 他ソースの全依存関係を解決した 後Xcode Cloudは プレXcodebuildスクリプトを実行します 次にXcode Cloudが アクションの対応する Xcodebuildコマンドを実行します Xcodebuildのステップが完了すると Xcode Cloudはポスト Xcodebuildスクリプトを 実行し 前に生成された アーティファクトを保存します ワークフローに複数のアクションがある場合 例えば複数のビルドのアクション またはビルド テスト 分析 アーカイブのアクションがある場合 Xcode Cloudはカスタム スクリプトを適切なタイミングで 各アクションに対して実行します カスタムスクリプトをXcode Cloudに追加するのは簡単です 適切な名前のシェルスクリプトを 「ci_scripts」フォルダに追加し このフォルダをワークフローに使用している プロジェクトファイルまたは ワークスペースと同じレベルの フォルダに配置します カスタムスクリプトはソースコード の一部であるため プルリクエストでスクリプトの変更をテストしたり 異なるブランチで動作を カスタマイズしたりできます Xcode Cloudが アクションを実行するときは 適切なタイミングで各スクリプトの 存在を見つけ出し 存在する場合は それらを実行します カスタムスクリプトを実行するために ワークフローを構成する必要はありません スクリプトがそこにある場合実行されます ci_scriptsフォルダの 名前と内部のスクリプトは この命名規則に 完全に従う必要があります Xcode Cloudがスクリプトを見つけて 実行できるようにするためです ワークフローで構成した環境変数は カスタムスクリプトで使用できます 秘密環境変数も含まれます さらにXcode Cloudは 様々な他の役立つ環境変数も 提供します これらの変数を使用して フローコントロールをスクリプトに追加して 実行するコマンドがワークフロー中 に正しいポイントで 実行されるようにできます 例えばアクションがiOSmacOS tvOS watchOSに対して 実行されているかを確認するには CI_PRODUCT_ PLATFORM変数の値を使用できます よりターゲットが絞られたシナリオでは多分 特定のワークフローのアーカイブ アクション中にのみ 実行するコマンドがあります CI_XCODEBUILD_ACTIONと CI_WORKFLOWの変数が アーカイブアクションと 特定ワークフローと一致しているか コマンド実行前に確認できます アクション中のカスタム スクリプトを見てみましょう 私のチームはFrutaという スムージーの注文Appの 業務を行っています セッションでFrutaのような Appの構ビルド テスト ディストリビューションを 行うためにワークフローを セットアップする方法を学んでいます Xcode Cloudでプルリクエストを 作成する度にビルドとテストを 実行しています またTest Flightでプルリクエストから チームメンバーにビルドを配布します これによりコードがマージされる前に変更を検証し サインオフできるようになります 今日はデバイスにインストールされているビルドが プルリクエストからのものであるかどうかを チームメンバーが簡単に 把握できるようにしたいです プルリクエストからビルドを作成している場合 これは別のAppアイコンを使って実行できます 想像できたと思いますが カスタムスクリプトを使用すると このセットアップが簡単になります どのように簡単になるのかを見てみましょう

XcodeでFruta プロジェクトを既に開いています カスタムスクリプトを追加する前に まずci_scriptsフォルダ をプロジェクトに追加する必要があります プロジェクトナビゲータでプロジェクトを選択し 下の+ボタンをクリックしてから を選択することで これは行えます フォルダ名にci_scriptsと入力します

次に設計者が作成したβAppアイコンセットを ci_scriptsフォルダに 追加してビルド中に カスタムスクリプトが所定の場所に スワップされるようにします これを行うにはFinderから ci_scriptsフォルダへ ドラッグします シートで選択済みのターゲットの チェックを解除して をクリックします

最後にプレXcodebuild スクリプトを追加してみましょう このスクリプトはXcodebuildコマンド の前に実行されFrutaの デフォルトAppアイコンセットの スワップに適宜使用されます 既に使用するスクリプトが作成されていますので ci_scriptsフォルダに 追加すればよいだけです

シートのターゲットのチェックを再度解除して をクリックします

スクリプトが所定の場所に配置されました それがどのようなことを 実行するのか詳細を見てみましょう まずビルドがプルリクエストから来ているときのみ Appアイコンが スワップアウトされるようにします ビルドがプルリクエストであるか をランタイムに確認するために Xcode Cloudが提供する 環境変数の1つを使用できます このために使用できるプル リクエスト関連の環境変数は いろいろありますがこの場合は CI_PULL_REQUEST _NUMBER環境変数が 設定されているかを確認します

またβAppアイコンのみを TestFlightに配布する ビルドに対して使用したいです Xcode Cloudはビルドを TestFlightに配布する度に まずプロジェクトのアーカイブを常にビルドします したがってこれを確認するよい方法は CI_XCODEBUILD_ ACTION環境変数の値が 「archive」であるかを検証することです

これらの環境変数の両方が 予期していた値になっている場合 rmとmvのコマンドを使用して 既存のAppアイコンセットを削除して βAppアイコンセットで置換します デフォルトとβのAppアイコン セット両方に対して 正しいパスを構築するために CI_WORKSPACE環境変数 を使用していることに注意してください あとすることはこれらの 変更付きでプルリクエストを 開いてXcode Cloudが TestFlightに対して Frutaをビルドし配布することです このプロセスを今説明する代わりに 事前にビルドを用意しておきました ここではXcode Cloudが プルリクエストブランチから Frutaをビルドし配布しています 電話のTestFlightAppで たった今追加した新しいβApp アイコンをビルドが使用しているか を検証できます プルリクエストをマージできて チームの全員が独自の プルリクエストのビルドで 同じβAppアイコンを見始めます Xcode Cloudでカスタム スクリプトを使用する方法を 確認してきましたがいくつか 注意すべき重要なことがあります カスタムスクリプトの標準的な 出力と標準的なエラーが 実行するアクションのログに含まれています タブから ダウンロードすることもできます スクリプトが予期される場合に 実行されていないように 見える場合は正しい名前になっているか ダブルチェックして プロジェクトやワークスペースと 共にci_scriptsフォルダに 配置してください カスタムスクリプトでエラーを トラブルシューティングするために 必ず役に立つロギングと レジリエンシを追加してください 例えば外部のサービスに対して スクリプトがネットワーク リクエストを行う場合 詳細ロギングを有効にした状態で リクエストを再試行するための ロジックを含めるとよいかもしれません さらにXcodeCloudにはスクリプトの 終了コードが反映されます スクリプトが0以外の値で 終了するとXcode Cloud はこれをエラーと見なし 全体のアクションを失敗させます これを利用してスクリプトで Xcode Cloudが アクションの残りを続行する前に 実行する必要のあるコマンドが 正常に処理されるようにできます 最後にテストアクションで テストをビルドして実行するために 複数の環境が使用されることに 注意する必要があります テストをビルドするために使用される環境のみで ソースコードがデフォルトで複製されます テストを実行する環境では ソースコードが複製されません ci_scriptsフォルダを 利用できるようにするだけです 結果として ポストクローンスクリプトは これらの環境では実行されず 他のシェルスクリプトや小型ツールなどの カスタムスクリプトとその依存関係は ci_scriptsフォルダ内に すべて含める必要があります カスタムスクリプトと環境変数には 2つのパワフルなツールがあり これによりワークフローの動作を カスタマイズできます 次に同僚のYanがXcode Cloudのある追加のリポジトリ を使用してSwiftパッケージや ワークフローの他の依存関係を 使用できるようにする方法を 説明します Itai ありがとうございます 多くのプロジェクトはツール ライブラリ フレームワークを 使用してビルドされています これらの依存関係はビルドを成功させるために 複数のプロジェクトで 共有されるGitリポジトリで ホストされることがよくあります Xcode Cloudはこれらの 追加のリポジトリを追加するのを 自動的に支援します 例えば 新機能を追加してFruta Appに対してユーザが知人を 招待してドリンクを共有できる ようにしたいと考えています 別のチームが似た機能を実装しています 「InvitationsKit」 というパッケージを再利用します プライベートGitリポジトリでホストされ チームで共有されているものです このパッケージを追加する方法を見てみましょう FrutaプロジェクトのXcodeです メニューからパッケージを追加し を選択できます 既にNature Labsに 組織内のパッケージのリストを含む パッケージコレクションを 共有させています InvitationsKitを選択し をクリックします 現時点では依存関係が追加され メニュー からこの新しい依存関係を コミットしてブランチ 変更をプッシュします

ブランチから新しいコミットを 受け取ると新しいビルドを 開始するXcode Cloudのワークフローを セットアップします この新しいコミットは新しい ビルドを開始する必要があります これがこの依存関係を追加する 初めての機会であるため ビルドが失敗することを予期しています Xcode Cloudに InvitationsKit リポジトリに対するアクセス権がないからです しかしXcode Cloudは この問題に対処するために簡単な UIを提供しています Apple Store Connect の Xcode Cloudに移動して この新しいビルドを見てみましょう 予期したようにビルドは失敗しています Xcode Cloudは警告の バナーを表示しています これはリポジトリにアクセスするの に問題がありアクセス権を付与する オプションを提供することを示しています 先に進み ボタンをクリックします

すると設定ページに移動します ここではinvitationsKit リポジトリリンクにホバーし をクリックできます

ソースコントロールサービスによっては Xcode Cloudを承認する ようにダイレクトされ これによりリポジトリにアクセス するようになることもあります 先に進みGithubの InvitationsKitに

対してアクセス権を提供しました ここでXcode Cloudに 戻るとと表示されています この時点でビルドを再実行できます

このビルドが今回はパスすることを予期しています のセクションに戻り 接続されている全リポジトリを 見つけることができます 使用されなくなっている場合は そこからのアクセスを拒否することもできます Xcode Cloudは ビルド中に新しく参照されている リポジトリを検出します Xcode Cloudがアクセス できない依存関係を追加すると この問題を修正するためにUIが すばやく簡単な方法を提供します これはどのGitオペレーションでも有効です カスタムスクリプト内のリポジトリの複製や Gitサブモジュールの参照も含まれます これは他のすべての依存関係管理 ツールにも適用されます このデモで新しいSwift パッケージコレクション機能を 使用して追加パッケージを 含めました 詳細を確認する場合は「コレクションを使用して Swiftパッケージを検出して キュレート」を参照してください これまでにXcode Cloud 内のビルドをカスタマイズする 方法を説明してきました しかしある人とそのチームが 外部のサービスを通じて 協業したいこともあるでしょう 例えば新しいビルドが準備完了に なったときにβテスターに 通知したいことがあるかもしれません Webhookが出番となるのは このようなときです WebhookはXcode Cloudにサービスと通信を 行う方法を提供します ビルドのライフサイクルの 様々なステージで送信される リッチペイロードにより ワークフローを更に自動化し チームの協業を 促進することができます 詳細を確認してみましょう Xcode CloudではWebhookを セットアップでき これにより ビルドの3つの異なるステージで リアルタイムの更新を行うことができます まずコードをプッシュしたか ビルドを手動で開始したため ビルドが作成されたとき 次にビルドが開始しているとき 最後にビルドが失敗しても成功しても関係なく ビルドが完了しているときです 新しいWebhookが プロジェクトに追加される方法を 見てみましょう Webhookの 追加はXcode Cloudでは 簡単です 左の列でタブをクリックします Webhookをクリックし +ボタンをクリックします するとAppやサービスに Webhook名ならびにHTTP リクエストを受け取り処理できるURLを 入力することが求められます 次にをクリックします Xcode Cloudを 利用すると1つの製品につき最大 5つのWebhookを作れます 各Webhookに一意の名前を つけて必ず簡単に 識別できるようにしてください エンドポイントに送信される ペイロードはビルドと製品の情報の あるJSON Blobです この情報とはApp Store Connect Appケーション ワークフロー 製品ビルドなどを指します HttpRequestを介して 送信されるペイロードを受信し 処理するためにAppやサービスを セットアップする必要があります AWS LambdaでSwift を使用して達成する方法について サンプルコードを見てみましょう まずリクエストを受け取ります 次にペイロードをJSON オブジェクトに解読します そしてワークフローの名前とビルドの状態を 確認します ワークフローがリリースワークフローで ビルドの状態が成功している場合 メッセージをTwitterに 投稿してテストユーザやβユーザに テストに利用できるようになったことを知らせます 最後にステータスコード200番台を返して Webhookのリクエストが 正常に処理されたことを識別します Swiftのサーバレス機能の実行に ついて詳細を確認する場合は WWDC 2020のこの セッションを確認してください エンドポイントが正常な ステータスコードを返さない場合 Xcode Cloudが リクエストを再送しようとします Xcode Cloudを使うと エンドポイントに配布された Webhookのコンテンツを 簡単に点検できるようにもなります App StoreConnectのXcode Cloudに移動します 設定と Webhookをクリックします 点検するWebhookを選択します すると様々なタイムスタンプのデリバリのリストが 表示されますので 興味のあるもの1つを選択します これはサービスに送信された リクエストと受信された 応答を示しています Xcode Cloud Webhookでできることは多数 あります 2 3の追加の例をここで挙げてみます バグをチェックするシステムから 問題を自動的に作成したり 解決したりすることができます ビルドが失敗したときに通知を ページング装置に送信します 複雑なリリースワークフローの一部として ダウンストリームビルドを開始します Webhookの完全なコンテンツを使用した ワークフローの拡張の場合 限度はありません このセッションで学習したことを まとめてみましょう まずビルドのための環境変数を 受け渡す方法を学習しました 次にビルドプロセスをカスタマイズするために スクリプトをセットアップする方法 プロジェクトの追加リポジトリを 扱う方法を説明しました 最後にビルドライフサイクルの 様々なステージでXcode Cloudからコールバックを 受け取るためにWebhookを セットアップする方法を学習しました これらの機能がチームの 日々のワークフローを 改善できることを願っています ご覧いただきましてありがとうございます ♪