CI/CDからテストを実行する

StudioのCI/CD画面は、GitHub ActionsまたはGitLab CI用のパイプラインファイルを作成します。このガイドでは、そのファイルが実行する内容、ジョブを実行できる3つの場所、シークレット、JUnit XMLと生成されるエビデンス、およびCIマシンで発生するエラーについて説明します。

パイプラインファイル

CI/CD画面で、GitHub ActionsまたはGitLab CI、ブラウザー、チェック項目、ジョブの実行場所を選択し、生成します。Studioはファイルをローカルで最初に検証し、同じ画面からコミットおよびプッシュすることができます。ターミナルから、nexus init --ci githubまたはnexus init --ci gitlabを実行すると、同じファイルが作成されます。

複数のブラウザを使用する場合、GitHub はブラウザごとに 1 つのジョブを実行し、fail-fast: false を設定します。各ジョブには --project=<browser> が追加されます。お選びいただいたチェックにより、--visual、--a11y、--chaos=、--loop=、または --no-retry が追加されます。

終了コードと JUnit XML

nexus ci は指定したテスト（TC1,TC2）または --all を実行し、合格した場合は 0、失敗した場合は 1、何も実行されなかった場合またはコマンドが誤っていた場合は 2 で終了します。JUnit XML を evidence/ci/junit.xml に書き出します。--junit=<path> を指定すると別の場所に書き出します。

ジョブの実行場所：3 つのオプション

いずれのオプションも、アクティベーション済みのマシンが必要です。エンジンはアクティベーションのないマシンではスイートを実行しません。また、アクティベーション済みの各マシンはプランのカウントに含まれます（プランとマシン）。クラウドホスト型ランナー（runs-on: ubuntu-latest）はジョブごとに新しい仮想マシンを起動するため、マシンを保持しません。永続的なランナーを独自にご用意ください。

オプション A：Studio のマシン上のセルフホスト型ランナー

1. Nexus Studio がインストールおよびアクティベートされている Windows 11 PC またはミニ PC に、ランナーを登録してください。GitHub の場合はリポジトリの Settings、Actions、Runners、New self-hosted runner から、GitLab の場合は Settings、CI/CD、Runners から登録できます。
2. CI/CD 画面で My machine を選択してください。ファイルには GitHub の場合 runs-on: [self-hosted]、GitLab の場合 tags: [self-hosted] と記載されます。
3. Studio をアクティベートした Windows ユーザーとしてランナーを実行してください。エンジンはそのユーザーのプロファイル内の .sentinel-studio\license.json からアクティベーション情報を読み取るため、別のアカウントで実行されているランナーサービスでは見つかりません。

このジョブはマシンのアクティベーションを使用します。マシン 1 台につき 1 つのアクティベーションで、すでにプランに含まれており、パイプラインにキーは不要です。Studio が警告しているとおり、セルフホスト型ランナーはプライベートリポジトリのみでご使用ください。パブリックリポジトリでは、プルリクエストを開いた誰もがお客様のマシン上でコードを実行できてしまいます。

オプション B：VPS 上のランナー（コンテナ内）

Ubuntu 24.04 LTS x86_64、Docker Engine および Compose v2 がインストールされた VPS で、SSH キー認証で接続できるものが必要です。これはプランの 1 マシンとしてカウントされます。

1. CI/CD画面で、My machine + Dockerを選択します。パイプラインファイルに加えて、Studioはdocker-compose.sentinel-runner.yml、Dockerfile.runner、およびランナーの2つのエントリポイントスクリプトをワークスペースに書き込みます。Dockerfile.runnerはmcr.microsoft.com/playwright:v1.62.1-nobleから開始します。
2. 画面には、Studio自身のターミナルではなく、VPS上のSSHセッションに貼り付けるコマンドが表示されます。GitHubの場合は1時間有効な登録トークンを取得し、REPO_URL、RUNNER_TOKEN、RUNNER_NAMEを設定します。GitLabの場合は、GITLAB_URLとGITLAB_RUNNER_TOKENを設定します。その後：

docker compose -f docker-compose.sentinel-runner.yml up -d --build sentinel-runner
docker compose -f docker-compose.sentinel-runner.yml up -d sentinel-runner-gitlab

最初の行はGitHub用、2番目の行はGitLab用です。Linuxコンテナ内では、ライセンスは/etc/machine-idによってマシンを識別します。ホストのファイルを読み取り専用（/etc/machine-id:/etc/machine-id:ro）でマウントし、ランナーのホームにある.sentinel-studioフォルダーをボリューム上に保持することで、再ビルド後もアクティベーションが維持されます。パイプラインファイルからではなく、nexus license activateとお手持ちのキーを使って、手動で一度だけアクティベートしてください。

現在、ランナーイメージはVPS上でDockerfile.runnerからビルドされます。リポジトリにはまだコンテナレジストリがありません。StudioのVPSランタイムが実行するものと同じ、GitHub Container Registry上に公開されたイメージは、次のリリースで提供される予定です。

オプションC：CIジョブがSSH経由でホスト上で実行を開始する

ジョブは任意のランナー上で小規模なまま維持され、StudioのSSHランタイムが想定しているとおり、テストスイートはワークスペースとエンジンが配置されたお客様所有のホスト上で実行されます。CI/CD画面ではこのジョブは生成されません。これらはStudio自身のSSHランタイムが使用するオプションです：

ssh -o BatchMode=yes -o StrictHostKeyChecking=yes -o ConnectTimeout=8 <user>@<host> "cd <path> && node bin/nexus.js ci --all"
scp -r -o BatchMode=yes -o StrictHostKeyChecking=yes <user>@<host>:<path>/evidence ./evidence

• 鍵認証のみ。 BatchMode=yesによりパスワードが要求されることはありません。CIシークレットからジョブのみが読み取り可能なファイルに秘密鍵を書き込み、ジョブの終了時に削除します。
• StrictHostKeyChecking=yes。 ホストの鍵はすでにランナーのknown_hostsに存在している必要があります。CI変数にホストの公開鍵行を保持し、最初のsshの前にそこに書き込んでください。絶対にnoに設定しないでください。
• 終了コードが返されます。 sshはリモートコマンドのコードで終了するため、スイートが失敗するとステップも失敗し、scpによってJUnit XMLを含むエビデンスがアーティファクトステップのために取得されます。
• ホストは自身のライセンスをチェックし、プランの1台のマシンとしてカウントされます。

シークレット

• トークン、Webhook URL、SSH秘密鍵はCIシークレットとして保存してください。GitHubではSettings、Secrets and variables、Actions、またはgh secret set <KEY>を使用します。GitLabではSettings、CI/CD、Variablesでマスクされた変数として保存します。リポジトリ、パイプラインファイル、ログには絶対に保存しないでください。
• 生成されたGitHubワークフローは、Nexusのステップでのみ、secrets.<KEY>から連携キー（TELEGRAM_*、SLACK_ENABLED、SLACK_WEBHOOK_URL、JIRA_*、および通知スイッチ）のみを読み取ります。CI/CD画面にはそれぞれに対応するgh secret setコマンドが一覧表示されます。ghから値の入力が求められ、画面には何も出力されません。
• ライセンスキーはCIに配置するべきではありません。永続ランナーを手動で一度アクティベートしてください。キーは一度だけ送信され、保持されません。プロセス上どうしてもCIシステム内にキーが必要な場合は、マスクされたシークレットとしてのみ保存してください。生成されたパイプラインがそれを読み取ることはありません。
• ステップ内でシークレットを絶対にechoしないでください。エンジンは、JUnitの失敗メッセージやログなど、エビデンスとして保存するテキストからシークレットを除去しますが、ジョブ自体のコンソール出力からは除去しません。また、CIサービスはシークレットとして保存された値のみをマスクします。

アーティファクトとしての JUnit XML とエビデンス

• GitHub は、実行の成否にかかわらず、evidence/ を nexus-evidence として、マトリックスを使用している場合はブラウザごとに1つの nexus-evidence-<browser> としてアップロードします。JUnit XML はその中の evidence/ci/junit.xml にあります。
• GitLab は evidence/ を保持し、evidence/ci/junit.xml を JUnit レポートとして報告するため、失敗したテストがマージリクエストに表示されます。
• Studio から、CI/CD 画面で GitHub ワークフローの実行を開始し、そのエビデンスをワークスペースの evidence/ci-remote/run-<id> にダウンロードできます。
• コピーの保存場所。 アーティファクトとは、スクリーンショットやログを含むエビデンスのコピーであり、CI サービスのストレージ上に保存されます。ホステッドサービスの場合、それは他者のハードウェア上となります。ポリシーで許可されているアーティファクトの保持期間を設定するか、エビデンスをランナー上に保持して evidence/ci/junit.xml のみをアップロードしてください。

トラブルシューティング

クラウドホステッドまたはエフェメラル（使い捨て）ランナーでの SEAT_LIMIT

新しい仮想マシンはライセンス上それぞれ新しいマシンとみなされるため、エフェメラルランナーではジョブごとにアクティベーションが必要になります。プランのすべてのマシンがアクティブになると、SEAT_LIMIT（「プランのすべてのマシンが使用中です。アカウントで1台をディアクティベートしてください。」）によりアクティベーションが拒否されます。永続的なセルフホステッドランナー（オプションAまたはB）を使用し、アカウントの License & machines で使用しなくなったマシンをディアクティベートしてください（SEAT_LIMIT の詳細）。

ランナーが数日間オフラインだった場合

マシンのライセンスは、少なくとも7日ごとに検証される必要があります。その後、通知とともにさらに4日間の猶予があり、その後読み取り専用になります。チェックが成功するまでスイートは実行されず、エビデンスは読み取り可能なまま維持されます。オンラインに戻ったランナーでは、nexus license renew で再チェックが行われます（オフラインでの作業）。

コンテナ内での「no /etc/machine-id」

コンテナ内にライセンスが読み取るためのマシン ID がありません。ホストのマシン ID を -v /etc/machine-id:/etc/machine-id:ro としてマウントするか、compose ファイルの volumes: の下に同じ行を追加してください。

ジョブが終了コード 2 で終了する

何も実行されませんでした。ID に一致するテストがなかったか、コマンドが間違っていました。GitHub の tc_ids や GitLab の TC_IDS など、nexus ci に渡された ID を確認してください。

ホストキーの検証に失敗しました

StrictHostKeyChecking=yes により、known_hosts に存在しないホスト、またはキーが変更されたホストが拒否されました。ホスト自体でフィンガープリントを確認した上で、信頼できるソースからそのホストのキーを追加してください。チェックを無効にしないでください。