Customize your advanced Xcode Cloud workflows

ハイライト

Apple は環境変数、カスタムスクリプト、追加の Git リポジトリ認証、Webhook を Xcode Cloud に追加し、開発者がチームの内部ツール、プライベート依存関係、外部サービスをクラウドビルドプロセスに統合できるようにします。

主要内容

多くのチームのビルドプロセスは、長い間「コンパイルする」という段階を超えていました。

テスト環境はステージング API に接続する必要があり、リリース環境は実稼働 API を使用する必要があります。 PR ビルドでは、テスターがベータ版を正式版と認識しないようにアイコンを変更する必要があります。アプリケーションはプライベート Swift パッケージに依存しているため、CI はそれを対応するリポジトリにプルできる必要があります。ビルドが完了したら、チームはテスターに自動的に通知するか、下流のリリースプロセスをトリガーしたいとも考えています。

これらの手順をローカルで完了すると、構成は各開発者のコンピュータに分散されてしまいます。環境変数の設定を忘れる人もいれば、実行するスクリプトの量が減ったり、プライベートウェアハウスのアクセス許可を持っていない人もいて、ビルド結果に一貫性がありません。

Xcode Cloud の基本的なワークフローでは、アプリケーションの構築、テスト、アーカイブ、配布がすでに可能です。このセッションでは、実際のチームに近いレイヤー、つまりチーム独自のプロセスに合わせてワークフローを調整する方法について説明します。

Apple には 4 つの入り口があります。環境変数は、構成をビルド環境に渡します。ci_scripts内部のシェルスクリプトは、固定フェーズでカスタムコマンドを実行します。追加のリポジトリ承認により、プライベート依存関係をクラウド内に構築できるようになります。 Webhook は、ビルドライフサイクル中に HTTP リクエストを外部サービスに送信します。

これらの機能の共通の目標は明確です。それは、もともとチーム Wiki に書かれたステップ、チャット記録、個人のシェル設定を Xcode Cloud の反復可能なワークフローに組み込むことです。

詳細

環境変数を使用してビルド構成を渡します。

(01:44) 一般的なシナリオは、環境の切り替えをテストすることです。アプリケーションは特定の API サービスに依存しています。正式に配布される場合にのみ、テスト中および運用中にステージングにアクセスする必要があります。コード内に URL をしっかりと記述すると、同じコードで複数のワークフローを処理することが困難になります。

Xcode Cloud の環境セクションは、キーと値の形式で環境変数をサポートします。変数はワークフロー構成に属しているため、ソースコードリポジトリに送信する必要はありません。ワークフローが実行されるたびに、Xcode Cloud はこれらの変数をアクションが実行される一時環境に設定します。

Environment variables in Xcode Cloud

API_BASE_URL=https://staging.example.com
CI_WORKFLOW=<current workflow name>
CI_PRODUCT_PLATFORM=<iOS | macOS | tvOS | watchOS>
CI_XCODEBUILD_ACTION=<build | test | analyze | archive>

キーポイント:

API_BASE_URL: チームはワークフローでビジネスサービスアドレスを構成でき、テストプロセスはステージングアドレスを使用します。
CI_WORKFLOW: Xcode Cloud によって提供される変数。現在実行中のワークフローを決定するために使用できます。
CI_PRODUCT_PLATFORM: Xcode Cloud によって提供される変数。現在のアクションがどの Apple プラットフォーム向けであるかを決定するために使用できます。
CI_XCODEBUILD_ACTION: Xcode Cloud によって提供される変数。現在のアクションがビルド、テスト、分析、アーカイブのいずれであるかを決定するために使用できます。

(02:37) 機密情報には秘密の環境変数が使用されます。 API キーまたはアクセストークンは暗号化して保存できます。復号化された値は、アクションが実行される一時的な環境にのみ表示され、ログでは隠され、ワークフローエディターでクリアテキストを再度表示することはできません。

Secret environment variables

API_TOKEN=<encrypted value>
ACCESS_TOKEN=<encrypted value>

キーポイント:

API_TOKEN：APIキーなどの機密性の高い値の保存に適しています。
ACCESS_TOKEN：外部サービスにアクセスするためのトークンを保存するのに適しています。
<encrypted value>: Xcode Cloud は暗号化された値を保存し、実行時に一時環境で復号化します。

ci_scripts を使用してカスタムビルドステップを挿入する

(03:50) カスタムスクリプトは、ソースコードリポジトリに配置されるシェルスクリプトです。 Xcode Cloud は、固定時間に実行される 3 種類のスクリプトをサポートしています。

ci_scripts/
  ci_post_clone.sh
  ci_pre_xcodebuild.sh
  ci_post_xcodebuild.sh

キーポイント:

ci_post_clone.sh: メインウェアハウスのクローンが作成された後に実行します。
ci_pre_xcodebuild.sh: 依存関係の解決が完了したら、xcodebuild実行前に実行します。
ci_post_xcodebuild.sh：xcodebuild完了したら、実行すると、Xcode Cloud によってビルドプロダクトが保存されます。
ci_scripts: フォルダー名は正確に一致し、ワークフローで使用されるプロジェクトまたはワークスペースと同じレベルに配置される必要があります。

(09:03) デモの Fruta アプリケーションには特定の要件があります。PR ビルドが TestFlight を通じてテストのためにチームに配布されるとき、アプリケーションアイコンはベータアイコンに置き換えられる必要があります。このようにして、テスターは、現在インストールされている PR ビルドが現在インストールされている PR ビルドであることを携帯電話上ですぐに認識できます。

#!/bin/sh

#  ci_pre_xcodebuild.sh
#  Fruta
#
#  Made in Vancouver, Canada
#

if [[ -n $CI_PULL_REQUEST_NUMBER && $CI_XCODEBUILD_ACTION = 'archive' ]];
then
    echo "Setting Fruta Beta App Icon"
    APP_ICON_PATH=$CI_WORKSPACE/Shared/Assets.xcassets/AppIcon.appiconset

    # Remove existing App Icon
    rm -rf $APP_ICON_PATH

    # Replace with Fruta Beta App Icon
    mv "$CI_WORKSPACE/ci_scripts/AppIcon-Beta.appiconset" $APP_ICON_PATH
fi

キーポイント:

#!/bin/sh: シェルによって実行されるスクリプトを宣言します。
ci_pre_xcodebuild.sh: スクリプト名によってどこに配置されるかが決まります。xcodebuild前に走ります。
CI_PULL_REQUEST_NUMBER: Xcode Cloud によって提供される変数。値がある場合、このビルドがプルリクエストからのものであることを意味します。
CI_XCODEBUILD_ACTION = 'archive': TestFlight は配布前にアイコンをアーカイブするため、アーカイブアクションでのみアイコンを変更します。
echo "Setting Fruta Beta App Icon": トラブルシューティングを容易にするために、現在の操作をアクションログに書き込みます。
APP_ICON_PATH=$CI_WORKSPACE/...：使用CI_WORKSPACEプロジェクト内でリソースパスを組み立てます。
rm -rf $APP_ICON_PATH：デフォルトのアプリアイコンセットを削除します。
mv "$CI_WORKSPACE/ci_scripts/AppIcon-Beta.appiconset" $APP_ICON_PATH：バンドルci_scriptsのベータ版アイコンは、デフォルトのアイコン位置に移動されます。

(10:48) スクリプトの標準出力と標準エラーはアクションログに記録され、[アーティファクト] タブからダウンロードすることもできます。スクリプトの終了コードはアクションの結果に影響します。ゼロ以外の終了コードにより、Xcode Cloud はアクションが失敗したと判断します。

#!/bin/sh

set -e

echo "Run a required custom command"
# your command here

キーポイント:

set -e: コマンドが失敗したときにスクリプトを停止し、できるだけ早く失敗を明らかにします。
echo: スクリプトが実行されたかどうかを見つけやすくするために、主要なステップをログに書き込みます。
# your command here: チームがアクションで実行する必要があるコマンドに置き換えられます。

Xcode Cloud が追加の Git リポジトリにアクセスできるようにします

(12:41) 多くのプロジェクトは、共有ライブラリ、ツール、またはフレームワークに依存しています。これらは通常、チームのプライベート Git リポジトリに配置されます。 Xcode Cloud がプロジェクトをビルドするときに、これらのリポジトリにアクセスする権限がない場合、ビルドは失敗します。

デモの Fruta には、と呼ばれる機能が追加されます。InvitationsKitプライベート Swift パッケージ。開発者は、Xcode のパッケージの追加を通じて依存関係を追加します。送信してプッシュした後、Xcode Cloud の新しいビルドはウェアハウスにアクセスできないことを検出するため、App Store Connect に認証プロンプトが表示されます。

Additional repository flow

1. Add InvitationsKit in Xcode
2. Commit and push the package dependency
3. Xcode Cloud starts a build
4. Build fails because repository access is missing
5. Open Manage Repositories
6. Grant access to the InvitationsKit repository
7. Rerun the build

キーポイント:

ステップ 1: 依存関係は通常どおり Xcode からプロジェクトに追加されます。
ステップ 3: ワークフローは、新しいコミットによって自動的にトリガーされます。
ステップ 4: 初めてプライベートリポジトリを参照するとき、Xcode Cloud はアクセスできない可能性があります。
ステップ 5: 失敗ページには、「リポジトリの管理」エントリが表示されます。
ステップ 6: 承認アクションは、確認のために GitHub などのソースコードサービスにジャンプする場合があります。
ステップ 7: 認証が完了したら、ビルドを再実行して依存関係をプルします。

(16:07) このメカニズムは Swift パッケージに限定されません。 Xcode Cloud は、ビルド中に新しく参照された Git リポジトリを検出します。複製されたリポジトリ、Git サブモジュール、およびカスタムスクリプト内の他の依存関係管理ツールによって参照される Git リポジトリも、同じ承認プロセスを通過します。

Repository references detected by Xcode Cloud

- Swift package dependency
- Git clone inside a custom script
- Git submodule
- Git repository used by another dependency manager

キーポイント:

Swift package dependency: デモ中InvitationsKitはこのカテゴリーに当てはまります。
Git clone inside a custom script: スクリプトでウェアハウスをアクティブにプルする場合、Xcode Cloud 権限も必要です。
Git submodule: プロジェクトがサブモジュールを使用する場合、Xcode Cloud も対応するウェアハウスにアクセスする必要があります。
another dependency manager: 他の依存ツールも、Git リポジトリを参照している限り、承認要件をトリガーする可能性があります。

Webhook を使用して外部サービスに接続する

(17:31) Webhook を使用すると、Xcode Cloud はビルドライフサイクル中にリアルタイムの更新を外部サービスに送信できます。チームはこれを使用して、ベータテスターに通知したり、問題を作成またはクローズしたり、ビルドが失敗したときにオンコールシステムに通知したり、ダウンストリームビルドをトリガーしたりできます。

Xcode Cloud は、3 つの段階で Webhook の送信をサポートします。

Xcode Cloud webhook delivery stages

1. Build is created
2. Build is starting
3. Build has completed

キーポイント:

Build is created: コードプッシュまたはビルドの手動開始後にトリガーされます。
Build is starting: ビルドの実行開始時にトリガーされます。
Build has completed: ビルド終了時にトリガーされ、成功と失敗の両方が対象となります。

(18:01) App Store ConnectのXcode Cloud設定にWebhookのエントリを追加します。 Webhook は製品ごとに最大 5 つまで作成できます。設定項目には、Webhook名とHTTPリクエストを受信できるサービスURLが含まれます。

Webhook configuration

Name: Release notification
URL: https://example.com/xcode-cloud/webhook
Limit: up to five webhooks per product
Payload: JSON blob with app, workflow, product, build, and more

キーポイント:

Name: 異なる Webhook を簡単に区別できるように、名前は一意に保つ必要があります。
URL: ターゲットサービスは、HTTP リクエストを受信して処理できる必要があります。
Limit: 製品ごとに最大 5 つの Webhook 。
Payload: Xcode Cloud は、App Store Connect アプリ、ワークフロー、製品、ビルド、その他の情報を含む JSON BLOB を送信します。

(19:16) Apple のロジック例は次のとおりです。サービスはリクエストを受信し、JSON ペイロードをデコードし、ワークフロー名とビルド状態をチェックします。リリースワークフローが正常に構築されたら、Twitter にメッセージを送信して、新しいバージョンをテストする準備ができていることをテスターに伝えます。処理が完了すると、ステータスコード 200 が返されます。

Webhook handler logic

1. Receive the request
2. Decode the payload to a JSON object
3. Check workflow name
4. Check build state
5. Post a message to Twitter when release workflow succeeded
6. Return HTTP 200

キーポイント:

ステップ 1: 外部サービスはリクエストを Webhook エンドポイントとして受信します。
ステップ 2: ペイロードは JSON であるため、最初にデコードする必要があります。
ステップ 3: ワークフロー名に基づいて公開プロセスをフィルターします。
ステップ 4: ビルド状態に基づいてビルド結果を判断します。
ステップ 5: リリースワークフローが成功した場合にのみテスターに通知します。
ステップ 6: リクエストが処理されたことを示すために 200 を返します。

(19:59) エンドポイントが成功ステータスコードを返さない場合、Xcode Cloud はリクエストの送信を再試行します。 App Store Connect で Webhook 配信レコードを表示して、送信されたリクエストと受信された応答を確認することもできます。

Webhook troubleshooting

- Xcode Cloud retries when the endpoint does not return a successful status code
- App Store Connect shows delivered requests
- App Store Connect shows received responses

キーポイント:

retries: 外部サービスが一時的に失敗すると、Xcode Cloud はそれを再送信します。
delivered requests: Xcode Cloud が実際に送信している内容を確認できます。
received responses: エンドポイントが何を返すかを確認し、形式やステータスコードの問題を特定できます。

重要ポイント

何をすべきか: PR ビルドのベータアイコンを自動的に変更します。 実行する価値がある理由: デモでの Fruta の使用CI_PULL_REQUEST_NUMBERそしてCI_XCODEBUILD_ACTIONビルドソースを確認するために、TestFlight テスターはデスクトップアイコンから PR バージョンを直接識別できます。 開始方法: プロジェクトの同じレベルのディレクトリに作成しますci_scripts/ci_pre_xcodebuild.sh、ベータ版を入れますAppIcon.appiconset入れますci_scripts、スクリプトで使用されますCI_WORKSPACEリソースを交換します。
やるべきこと: ワークフローごとに異なる API 環境を構成します。 実行する価値がある理由: 環境変数はワークフロー構成に属しているため、ステージング URL やトークンをウェアハウスに送信する必要はありません。シークレット変数は機密性の高い値を隠すこともできます。 開始方法: Xcode Cloud ワークフローの環境セクションに追加しますAPI_BASE_URL、API キーをシークレット環境変数に設定します。
やるべきこと: プライベート Swift パッケージをクラウドビルドに組み込みます。 価値がある理由: Xcode Cloud は、ビルドで参照される追加の Git リポジトリを検出し、App Store Connect での認証アクセスを提供します。 開始方法: まず、Xcode にパッケージを追加し、依存関係の変更を送信します。ビルドが失敗した後、「リポジトリの管理」を開き、プライベートリポジトリへのアクセスを許可して、ビルドを再実行します。
やるべきこと: ビルドが成功すると、ベータテスターに自動的に通知されます。 実行する価値がある理由: Webhook は、ビルドの作成、開始、完了時に JSON ペイロードを送信し、外部サービスはワークフローとビルドの状態に基づいて通知するかどうかを決定できます。 開始方法: Xcode Cloud 設定に新しい Webhook を追加します。URL は独自の HTTP エンドポイントを指します。リクエストを受信した後、サービスは JSON をデコードし、リリースワークフローが成功したかどうかを判断し、最終的に HTTP 200 を返します。
対処方法: ビルドが失敗した場合、稼働中のシステムに自動的に通知します。 実行する価値がある理由: Apple は、Webhook がビルドの失敗をページングシステムに送信できることを明示的に述べており、これはリリースプロセスとマスターブランチの保護に適しています。 開始方法: メインブランチワークフローの Webhook を構成し、エンドポイントでビルド状態を確認し、失敗した場合にチームの既存のアラームサービスを呼び出します。

Customize your advanced Xcode Cloud workflows

ハイライト

主要内容

詳細

環境変数を使用してビルド構成を渡します。

ci_scripts を使用してカスタムビルドステップを挿入する

Xcode Cloud が追加の Git リポジトリにアクセスできるようにします

Webhook を使用して外部サービスに接続する

重要ポイント

関連セッション

コメント

ハイライト

主要内容

詳細

環境変数を使用してビルド構成を渡します。

ci_scripts を使用してカスタム ビルド ステップを挿入する

Xcode Cloud が追加の Git リポジトリにアクセスできるようにします

Webhook を使用して外部サービスに接続する

重要ポイント

関連セッション

コメント

ci_scripts を使用してカスタムビルドステップを挿入する