APIの接続先や機能フラグのように、公開されても認証に使えない設定値は通常の環境変数にします。トークン、パスワード、秘密鍵など、アクセス権を与える値はSecretとして扱ってください。アプリに含めて配布する設定ファイルと、ビルド中だけ必要な認証情報も同じものとして管理しないことが重要です。

たとえば、アップロードスクリプトで外部サービスのトークンを使う場合、トークンをソースコードに書いたり、リポジトリへ追加したりするのは避けます。ログに値を出さないようにしていても、認証情報を参照できる処理や実行元が広すぎれば、漏えいの可能性は残ります。

Appleの環境変数リファレンスでは、Xcode Cloudが提供する変数も説明されています。自分で設定する値、ワークフロー間で共有する値、あらかじめ用意された値を区別し、独自の変数名と混同しないようにしましょう。

Xcode Cloudにカスタム環境変数を追加するときは、どこから始めればよいですか。
対象のワークフローの環境設定を開き、変数名と値を登録して、そのワークフローに割り当てます。画面上の名称や操作手順は変更されることがあるため、現在の手順はAppleのワークフロー環境変数の説明で確認してください。

開発用と公開用でワークフローが分かれているなら、まず公開用の認証情報を公開作業に必要な方だけへ割り当てます。共有変数は複数のワークフローで同じ値を使う場合に便利ですが、共有を設定したからといって、すべてのワークフローへアクセスを与える必要はありません。共有変数の作成と割り当てはAppleの共有環境変数ガイドに沿って確認します。

複数のワークフローで同じ設定を再利用できますか。
できます。共有変数を使う方法があります。ただし、値を再利用する範囲と、実際にその値を必要とするワークフローの範囲は別々に判断します。使わないワークフローからは割り当てを外し、チームの役割に応じて編集できる人も確認してください。Appleのワークフロー戦略と編集権限の説明も参照できます。

post-clone、pre-xcodebuild、post-xcodebuildは、実行されるタイミングと担当する処理が異なります。依存関係の準備、ビルド前の設定、ビルド後の成果物処理など、スクリプトが行う作業に合わせて変数を使ってください。各段階で使える情報や作業場所を同じと決めつけず、Appleのカスタムビルドスクリプトの仕様で確認します。

シェルスクリプトでは、値を直接表示するコマンドを避け、必須の変数が未設定なら処理を止める形にします。次は変数の参照方法を示す例です。API_TOKENには実際の認証情報を記入せず、Xcode Cloud側で設定します。

set -eu

: "${API_TOKEN:?API_TOKEN is required}"

# API_TOKENの値を出力せず、必要な処理だけを実行する
./upload-artifact.sh

スクリプト内でenvやprintenvを使って環境全体を出力すると、意図しない値までログに載るおそれがあります。デバッグ時も、認証情報そのものではなく「設定されているか」を確認する実装にしましょう。なお、参照できない変数がある場合は、名前の綴り、ワークフローへの割り当て、スクリプトの実行段階を順に見直します。

Secretがビルドログに表示されないようにするには、何を確認すればよいですか。
Secretとして登録したうえで、テスト用の値を使い、スクリプトの出力とビルドレポートに値が現れないことを確認します。AppleはカスタムビルドスクリプトでSecretを扱う際のログ出力について説明していますが、ログのマスクをアクセス権限の制御と同一視してはいけません。Secretとスクリプトのログに関するAppleの案内を読み、実際のワークフローでも確かめてください。

ビルドログに値が見えないことだけでは、認証情報を扱うスクリプトを誰が実行できるかまでは確認できません。ブランチ変更、プルリクエスト、手動実行、公開用ワークフローなど、実行のきっかけごとに、その処理が外部サービスへ接続する必要があるかを判断します。Secretに設定したという理由だけで、すべての実行元に認証情報を渡す設計にしないでください。

テストでは本物の認証情報を使わず、値を出力しない状態で「参照できる」「未設定なら失敗する」「失敗理由にSecretが含まれない」を確認します。ログに出た文字列は、マスク済みでも内容を再確認してください。

スクリプトが環境変数を読み取れないときは、どこを調べますか。
まず変数名の大文字・小文字を含む一致、対象ワークフローへの割り当て、実行されるスクリプト段階を確認します。次に、変数がその段階で参照できるかをAppleの環境変数リファレンスと照合します。設定した値が正しいワークフローに登録されているかも見直してください。

その後、認証情報を含まないテスト値で実際のビルドを実行します。成功時に値がスクリプトへ渡ることだけでなく、未設定時に安全に停止すること、失敗した処理の終了状態がビルド結果に反映されること、ログやレポートにSecretが含まれないことを確かめます。AppleはXcode Cloudのログ内容に関する案内も公開しているため、フィードバックとログに関する説明も確認材料になります。

Xcode Cloudのビルド環境は、手元のMacに設定した状態がそのまま保持される作業場所とは異なります。補助ツールの実行や一時的な環境の違いがエラーにつながる場合は、AppleのテクニカルノートTN3129を参照し、前提となる環境を見直してください。

Xcode Cloudは、ワークフローに沿ったビルドやカスタムスクリプトの実行に適しています。一方で、作業状態を継続して保持したい、対話しながら問題を追いたい、ホスト側の状態を自分で管理したい場合は、既存のワークフローだけで要件を満たせるかを確認する必要があります。Appleのワークフローリファレンスで実行条件を照合し、足りない部分だけを別の構成で補うのが堅実です。

既存の方法を続ける利点は、ビルドをワークフロー単位で管理できることです。反対に、状態を保つ作業や細かなホスト制御が必要なら、その要件を追加のスクリプトだけで無理に補えるか慎重に見極めます。Macを購入して常設すれば環境を手元で管理できますが、専用機の用意や保守が必要です。遠隔のMac環境も、アクセス方法や利用条件を確認してから選びましょう。必要であれば、KVMNODEの案内で現行のサービス情報を確認し、日本向けMac miniの購入情報とも比較できます。

ビルドスクリプトの認証情報を扱うなら、Secretの設定だけで完了とせず、対象ワークフロー、実行元、ログ、失敗時の挙動まで確認してください。作業状態を継続して保つことや対話的な調査が必要で、ワークフローだけでは環境制御が足りないと分かった場合は、遠隔Macの構築環境も選択肢になります。要件を整理したうえで、KVMNODEの現行情報を確認し、必要な環境だけを追加するか判断してください。