ドキュメントに関する現在のご利用体験についてお聞かせください。アンケートにご協力ください。

フロー実行を設定する

プラン: Free、Premium、Ultimate
提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

フローはエージェントを使用してタスクを実行します。

GitLab UIから実行されるフローは、CI/CDを使用します。
IDEで実行されるフローは、ローカルで実行されます。

フローがCI/CD経由で実行される環境を設定できます。独自のRunnerを使用したり、ジョブに変数を指定したりすることもできます。

Executorアーキテクチャ

フローがCI/CDで実行されると、Runnerは次の処理を行います:

@gitlab/duo-cliパッケージをnpmレジストリからダウンロードします。
GitLab Duo CLIを実行し、WebSocketを使用してGitLab Duo Workflow Serviceに接続します。
AIモデルの指示に従ってツール（ファイル操作、Gitコマンド）を実行します。

ExecutorのバージョンはGitLabによって管理され、定期的なリリースの一部として更新されます。

CI/CD実行を設定する

CI/CDでフローを実行する方法をカスタマイズするには、プロジェクトにエージェントの設定ファイルを作成します。

サポートされているキーとそのタイプについては、agent-config.yml参照を参照してください。

事前定義されたCI/CD変数を使用してagent-config.ymlを設定することはできません。フローを実行するジョブには変数を使用する必要があります。

エージェントの設定ファイルを作成する

プロジェクトのリポジトリに、.gitlab/duo/フォルダーを作成します。
そのフォルダー内に、agent-config.ymlという名前の設定ファイルを作成します。
必要な設定オプションを追加します。
ファイルをデフォルトブランチにコミットしてプッシュします。

プロジェクトのCI/CDでフローが実行されると、設定が適用されます。

完全なagent-config.ymlファイル例については、agent-config.yml参照を参照してください。

設定ファイルはプロジェクトのデフォルトブランチから読み取り専用です。他のブランチにコミットされたファイルは、それらのブランチからフローが実行されても無視されます。

セットアップスクリプトを設定する

フローの実行前に実行されるセットアップスクリプトを定義できます。これは、依存関係のインストール、環境の設定、または初期化に役立ちます。

セットアップスクリプトを追加するには、agent-config.ymlファイルに次のコマンドを追加します:

setup_script:
  - apt-get update && apt-get install -y curl
  - pip install -r requirements.txt
  - echo "Setup complete"

これらのコマンドは次のアクションを実行します:

メインのワークフローコマンドの前に実行されます。
指定された順序で実行されます。
単一のコマンドまたはコマンド配列として指定できます。

setup_scriptのユーザーコンテキストはDockerイメージによって異なります。デフォルトのGitLabイメージはrootとして実行されます。カスタムイメージは、イメージのUSERディレクティブで定義されたユーザーとして実行されます。setup_scriptがルートアクセス（例えば、システムパッケージをインストールするため）を必要とする場合、カスタムイメージが適切に設定されていることを確認してください。

setup_scriptコマンドはSRTが適用される前に実行され、その外部で実行されます。これらのコマンドは、トリガーするユーザーのOAuthトークン、サービストークン、およびID詳細を含む、フロー内のすべての環境変数にアクセスできます。セキュリティモデルと推奨される保護については、agent-config.ymlのセキュリティへの影響を参照してください。

キャッシュを設定する

後続のフローの実行を高速化するためのキャッシュを設定するには、agent-config.ymlファイルを設定して、実行間でファイルとディレクトリを保持します。キャッシュは、node_modulesなどの依存関係フォルダーや、Python仮想環境に役立ちます。

基本的なキャッシュ設定

特定のパスをキャッシュするには、次の内容をagent-config.ymlファイルに追加します:

cache:
  paths:
    - node_modules/
    - .npm/

キーを使用したキャッシュ

キャッシュキーを使用すると、異なるシナリオに応じてさまざまなキャッシュを作成できます。キャッシュキーは、キャッシュがプロジェクトの状態に基づいていることを保証するのに役立ちます。

文字列キーを使用する

cache:
  key: my-project-cache
  paths:
    - vendor/
    - .bundle/

ファイルシステムベースのキャッシュキーを使用する

ファイルの内容（ロックファイルなど）に基づいて動的なキャッシュキーを作成します。これらのファイルが変更されると、新しいキャッシュが作成されます。これにより、指定されたファイルからSHAチェックサムが生成されます:

cache:
  key:
    files:
      - package-lock.json
      - yarn.lock
  paths:
    - node_modules/

ファイルベースのキーとプレフィックスを組み合わせる

キャッシュキーのファイルから計算されたSHAと、プレフィックスを組み合わせます:

cache:
  key:
    files:
      - package-lock.json
    prefix: $CI_JOB_NAME
  paths:
    - node_modules/
    - .npm/

この例では、ジョブ名がtestで、SHAチェックサムがabc123の場合、キャッシュキーはtest-abc123になります。

キャッシュの制限事項

キャッシュキーの生成には、最大2つのファイルを指定できます。3つ以上のファイルが指定されている場合は、最初の2つのみが使用されます。
キャッシュのpathsフィールドは必須です。パスが指定されていないキャッシュ設定は効果がありません。
キャッシュキーのprefixフィールドではCI/CD変数をサポートしています。

IDトークンを設定する

フローからサードパーティサービスを認証するには、IDトークンを設定します。

IDトークンは、GitLab CI/CDが生成し、フローを実行するジョブに注入するJSON Webトークン（JWT）であり、永続的な認証情報を保存せずにキーレスのOpenID Connect（OIDC認証）を可能にします。例えば、IDトークンを使用してシークレットマネージャーからシークレットを取得するか、バイナリとGitコミットに署名できます。

IDトークンを設定するには、agent-config.ymlファイルにid_tokensブロックを追加します。各トークンにはaud（オーディエンス）クレームが必要です:

id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

network_policy:
  allowed_domains:
    - vault.example.com

audクレームは単一の文字列または文字列のリストにすることができます:

id_tokens:
  MY_ID_TOKEN:
    aud:
      - https://first.service.example.com
      - https://second.service.example.com

network_policy:
  allowed_domains:
    - first.service.example.com
    - second.service.example.com

各トークンは、トークンの名前を使用する環境変数としてフロージョブで利用できます。上記の例では、フローは$VAULT_ID_TOKENと$MY_ID_TOKENを使用できます。

トークン名が設定内の別の場所で宣言された変数名と一致する場合、IDトークンが優先されます。

IDトークンは、そのaudクレームを信頼するサービスへのアクセスを許可する認証情報です。各トークンに可能な限り狭いaud値を設定して、不正なトークンができるだけ少ないサービスで認証できるようにします。設定ファイルはデフォルトブランチから読み取られるため、フローがリクエストできるトークンを変更できるユーザーを制御するために推奨される保護を適用してください。

トークンペイロードとサードパーティサービスとの信頼を設定する方法の詳細については、IDトークンを使用したOpenID Connect（OIDC認証）を参照してください。

フローを実行するようにRunnerを設定する

CI/CDを使用するフローはRunnerで実行されます。

GitLab.comでは、フローはGitLabが提供するホスト型Runnerを使用できます。これらはデフォルトで有効になっています。

また、フロー用に独自のRunnerを設定するオプションもあります。

トップレベルグループでIPアドレス制限が有効になっている場合、ホスト型Runnerはフローに使用できません。ホスト型Runnerは、グループのIP許可リストに追加できないクラウドプロバイダープールからの動的IPアドレスを使用します。代わりに、トップレベルグループで独自のグループRunnerを設定します。

フロー用に独自のRunnerを設定するには:

インスタンスRunnerまたはトップレベルグループに割り当てられたグループRunnerを作成します。もしフローでプロジェクトRunnerまたはサブグループに割り当てられたグループRunnerを使用したい場合は、duo_runner_restrictions機能フラグ（GitLab Self-Managedのみ）をオフにします。
Runnerにgitlab--duoタグを追加して、フローのジョブをピックアップするようにします。Runnerにこのタグがない場合、フローを持つジョブは無期限にキューに入ったままになります。次のいずれかの方法を使用します:
- Runnerを作成する際に、タグフィールドにgitlab--duoと入力します。
- 既存のRunnerの場合は、Runnerが実行できるジョブを編集し、タグフィールドにgitlab--duoと入力します。
- config.tomlファイルでRunnerを設定する場合は、[[runners]]セクションにタグを追加します:
```
[[runners]]
  executor = "docker"
  tags = ["gitlab--duo"]
```
Runnerをdocker、docker-autoscaler、またはkubernetesのようなDockerイメージをサポートするexecutorを使用するように設定します。shell executorはサポートされていません。
トップレベルグループでIPアドレス制限が有効になっている場合は、RunnerのIPアドレスをグループのIP許可リストに追加して、Runnerがグループにアクセスできるようにします。
GitLab Self-Managedのみ。Runnerがフローが必要とするサービスに到達できることを確認してください:
- GitLabインスタンスからの送信接続を許可して、Agent Platformに接続します。
- Runnerからの送信接続を許可して、Agent Platformに接続します。
- 証明書チェーンに自己署名証明書があるインスタンスの場合は、追加のGitLab Duo CLI設定を完了します。

実行環境サンドボックスを使用してフローを保護する

ネットワークとファイルシステムの分離のために、実行環境サンドボックスを使用して、Runnerで実行されるフローを保護します。

サンドボックスを使用するには、次のいずれかのイメージを使用する必要があります:

Agent Platform用のデフォルトDockerベースイメージ
A SRTがインストールされたカスタムイメージ

Runnerをサンドボックスを使用するように設定するには、Runnerの設定でprivileged = trueを設定します。

例:

[[runners]]
  executor = "docker"
  tags = ["gitlab--duo"]
  [runners.docker]
    privileged = true

サンドボックスは次のイメージでは使用できません:

SRTがインストールされていないカスタムイメージ
ハード化されたUBI 9 Minimalイメージ