フロー実行を設定する

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

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

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

フローのセキュリティ

フローがGitLab CI/CDで実行される場合:

アクセスを制限するために、フローは複合アイデンティティを使用します。
それらは一時的なワークロードパイプラインを作成し、フローが完了すると削除されます。
フローが使用できるツールは、フローの目的に応じて制限されます。これらのツールには、マージリクエストの作成、実行環境でのローカルShellコマンドの実行などが含まれます。

デフォルトでは、フローはGitLabインスタンスにのみネットワークアクセスできます。ネットワークアクセスルールに関する詳細は、ネットワークポリシーを設定する方法を参照してください。この分離された環境により、Shellコマンドの実行による意図しない結果から保護されます。

GitLab UIでフローが自律的に実行されるのを防ぐため、フローの実行をオフにすることができます。

`agent-config.yml`のセキュリティ上の影響

.gitlab/duo/agent-config.ymlファイルは、setup_scriptで実行されるコマンドを含め、フローがCI/CDでどのように実行されるかを制御します。フローの実行方法により、このファイルへの変更は、コミットしたユーザー以外のユーザーにも影響を与えます。

クロスユーザー実行

フローは、コンポジットアイデンティティを通じてトリガーするユーザーのIDで実行されます。setup_scriptのコマンドは、トリガーしたユーザーのコンポジットアイデンティティ認証情報で実行され、設定をコミットしたユーザーの認証情報ではありません。

.gitlab/duo/agent-config.ymlへの書き込みアクセス権を持つユーザーは、別のユーザーのRunner環境で何が実行されるかに影響を与える可能性があります。このファイルへの変更は、その後プロジェクトでフローをトリガーするすべてのユーザーの実行コンテキストに影響を与えます。

公開される環境変数

Anthropic Sandbox Runtime（SRT）の外部で実行されるsetup_scriptの実行中、以下の機密性の高い変数が環境内に存在します:

GITLAB_OAUTH_TOKENとGITLAB_TOKEN: トリガーするユーザーのコンポジットアイデンティティを通じたOAuthトークン。
DUO_WORKFLOW_GIT_HTTP_PASSWORD: Git HTTPパスワード。
DUO_WORKFLOW_SERVICE_TOKEN: サービストークン。
DUO_WORKFLOW_GIT_USER_EMAILとDUO_WORKFLOW_GIT_USER_NAME: トリガーするユーザーのメールと名前。

公開される変数の完全なリストについては、フロー実行変数を参照してください。

推奨される保護

.gitlab/duo/agent-config.ymlファイルへの不正な変更のリスクを軽減するには、次の操作を行います:

直接的なプッシュを防ぐために、デフォルトブランチを保護します。
コードオーナーを使用して、.gitlab/duo/agent-config.ymlへの変更がマージされる前に、特定のオーナーからの承認を必須にします。例えば、CODEOWNERSファイルに以下を追加します:
```
.gitlab/duo/agent-config.yml @your-group/security-reviewers
```
このファイルを変更するマージリクエストについて、信頼できるメンテナーによるレビューを必要とする承認ルールを設定します。

Executorアーキテクチャ

フローがCI/CDで実行されると、Runnerは次のように動作します:

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

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

CI/CD実行を設定する

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

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

このシナリオでは、事前に定義されたCI/CD変数を使用できません。利用可能な変数のリストを参照してください。

設定ファイルを作成する

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

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

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

デフォルトのDockerイメージを変更する

デフォルトでは、CI/CDで実行されるすべてのフローは、GitLabが提供する標準のDockerイメージを使用します。このDockerイメージは、Anthropic Sandbox Runtime（srt）を使用して、ネットワーク保護を自動的に組み込みます。

Dockerイメージを変更し、独自のものを指定できます。独自のイメージは、特定の依存関係やツールを必要とする複雑なプロジェクトに役立ちます。イメージでネットワーク保護を使用するには、希望するバージョンでsrtをDockerイメージに追加します:

# Install srt sandboxing with cache clearing and verification
ARG SANDBOX_RUNTIME_VERSION=0.0.20
RUN npm cache clean --force && \
    npm install -g @anthropic-ai/sandbox-runtime@${SANDBOX_RUNTIME_VERSION} && \
    test -s "$(npm root -g)/@anthropic-ai/sandbox-runtime/package.json" && \
    srt --version

SRTおよびカスタムイメージへのインストール方法の詳細については、リモート実行環境サンドボックスを参照してください。

デフォルトのDockerイメージを変更するには、agent-config.ymlファイルに以下の設定を追加します:

image: YOUR_DOCKER_IMAGE

例:

image: python:3.11-slim

または、Node.jsプロジェクトの場合:

image: node:20-alpine

強化されたUBI 9 Minimalイメージ

GitLabは、Red Hat Universalベースイメージ（UBI）9 Minimalに基づく、強化された最小限のイメージバージョンも提供します。このイメージは、ネットワークが制限された、FedRAMPスタイル、またはその他のセキュリティに敏感な環境向けに設計されており、より小さいアタックサーフェス、非root実行、およびRed Hat UBIベースが求められます。

強化されたイメージは次の場所で公開されています: registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened

これはlinux/amd64とlinux/arm64の両方でビルドされ、デフォルトイメージと同じタグスキームを使用します:

:<short-sha>ビルドごと
:<git-tag>リリースごと

強化されたイメージを使用する

前提条件:

GitLab 18.10以降

強化されたイメージを使用するには、agent-config.ymlで設定します:

image: registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened:<tag>

イメージのコンテンツ

コンポーネント	バージョン
ベースイメージ	Red Hat UBI 9 Minimal
`git`	UBI 9 stock
`git-lfs`	UBI 9 stock
Node.js	20（UBI 9モジュールストリーム）
`npm`	Node.js 20とバンドル
`@gitlab/duo-cli`	プリインストール済み
`glab`（GitLab CLI）	プリインストール済み
ランタイムユーザー	非root、UID 1001（`duo-runner`）

イメージには@gitlab/duo-cliとglabが含まれているため、registry.npmjs.orgまたはregistry.gitlab.comへの送信アクセスはフロー実行時に不要です。

追加のパッケージでイメージを拡張する

強化されたイメージはUID 1001（duo-runner）として実行されます。agent-config.yml内のsetup_scriptもこの非rootユーザーとして実行されるため、microdnfでシステムパッケージをインストールすることはできません。

言語ランタイムまたはシステムパッケージを追加するには:

独自のFROMレイヤーでイメージを拡張します:

FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image-hardened:<tag>

USER root
RUN microdnf install -y python3.12 python3.12-pip && microdnf clean all
USER 1001

rootアクセスを必要としないプロジェクトの依存関係には、setup_scriptを使用します。例: pip install --user、npm install。

強化されたイメージを使用するタイミング

環境で以下が必要な場合に、強化されたイメージを使用します:

Red Hat UBIベースイメージ。例えば、FedRAMPまたは企業コンプライアンスの場合。
デフォルトでの非rootコンテナ実行。
Agent Platform自体が必要とする以上の言語ランタイムを持たない最小限のアタックサーフェス。
フロー実行時の送信インターネットアクセスなし（Agent Platformのすべての依存関係はプリインストール済み）。

複数の言語ランタイムをすぐに必要とする接続された環境での汎用フローには、デフォルトイメージを使用します。

カスタムイメージの要件

カスタムDockerイメージを使用する場合は、エージェントが正しく機能するために、次のコマンドが利用可能であることを確認してください:

git
npmと互換性のあるNode.jsバージョンを持つ@gitlab/duo-cli。詳細については、GitLab Duo CLIの前提条件を参照してください。

ほとんどのベースイメージには、デフォルトでこれらのコマンドが含まれています。ただし、最小構成イメージ（alpineバリアントなど）では、明示的にインストールする必要がある場合があります。必要に応じて、セットアップスクリプトの設定で不足しているコマンドをインストールできます。

GitLab 18.9以前では、カスタムイメージ内の新しいgitのバージョンでフローが失敗する可能性があるという既知のイシュー（587996）があります。このイシューは、@gitlab/duo-cliバージョン8.71.0で解決されました。

@gitlab/duo-cliバージョン8.71.0以前を使用している場合、新しいGitのバージョンでフローが失敗するのを避けるために、以下のいずれかを実行できます:

カスタムイメージでGitバージョン2.43.7または以前のものを使用します
@gitlab/duo-cliバージョン8.71.0を使用します。

さらに、フロー実行中にエージェントが行うツール呼び出しによっては、他の一般的なユーティリティが必要になる場合があります。

たとえば、Alpineベースのイメージを使用する場合:

image: python:3.11-alpine
setup_script:
  - apk add --update git nodejs npm

セキュリティとパフォーマンス

カスタムDockerイメージを使用する場合、環境サンドボックスは、Anthropic Sandbox Runtime（SRT）がカスタムイメージに含まれている場合にのみ適用されます。SRTが含まれていない場合、フローはRunnerから到達可能な任意のドメインと完全なファイルシステムにアクセスできます。

カスタムイメージでネットワーク分離が必要な場合は、イメージにSRTをインストールし、ネットワークポリシーを設定するか、Runnerでネットワークレベルの制御（ファイアウォールルールやネットワークポリシーなど）を設定します。

ジョブの起動時間を約15〜20秒短縮するには、@gitlab/duo-cli npmパッケージとglabCLIをカスタムイメージに含めます。強化されたイメージには、両方のツールがプリインストールされています。

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

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

セットアップスクリプトを追加するには、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がrootアクセスを必要とする場合（例えば、システムパッケージをインストールするため）、カスタムイメージがそれに応じて設定されていることを確認してください。

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

オフライン環境でカスタムイメージを使用する

Runnerが外部レジストリに到達できないオフライン環境では、@gitlab/duo-cliを含むカスタムexecutorイメージをプリビルドできます。GitLab DuoCLIがイメージにすでに含まれている場合、フロー起動はnpmダウンロードステップをスキップします。

前提条件:

管理者アクセス権。
GitLab 18.9以降。
イメージをビルドし、アーティファクトをダウンロードするためのオンラインマシンへのアクセス。

オフライン環境用にフローを設定するには:

オンラインマシンで、GitLab DuoCLIを使用してカスタムイメージをビルドします:

FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.0.6
RUN npm install -g @gitlab/duo-cli@8.86.0

あるいは、npmを完全に回避するには、GitLabパッケージレジストリからスタンドアロンのバイナリをダウンロードします:

FROM registry.gitlab.com/gitlab-org/duo-workflow/default-docker-image/workflow-generic-image:v0.0.6
COPY duo-linux-x64 /usr/bin/duo
RUN chmod +x /usr/bin/duo

スタンドアロンのバイナリをダウンロードするには、次のコマンドを実行します:

curl --location "https://gitlab.com/api/v4/projects/46519181/packages/generic/duo-cli/8.86.0/duo-linux-x64" \
  --output duo-linux-x64

イメージをオフライン環境に転送します。例えば、Dockerを使用して、次のコマンドを実行します:

# On an online machine
docker save my-duo-executor:latest -o duo-executor.tar

# Transfer `duo-executor.tar` to the offline environment

# On an offline machine
docker load -i duo-executor.tar

イメージを内部コンテナレジストリにプッシュします。
カスタムイメージレジストリを設定します:
1. 右上隅で、管理者を選択します。
2. 左側のサイドバーで、GitLab Duoを選択します。
3. 設定の変更を選択します。
4. イメージレジストリテキストボックスに、内部レジストリのURL（例えば、registry.internal.example.com）を入力します。
上部のバーで、検索または移動先を選択して、プロジェクトを見つけます。
カスタムイメージを使用するには、agent-config.ymlファイルを更新します:
```
image: registry.internal.example.com/duo-executor:latest
```

キャッシュを設定する

後続のフローの実行を高速化するためにキャッシュを設定するには、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ウェブトークン（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認証）を参照してください。

すべてのオプションを使用した設定例

利用可能なすべてのオプションを使用したagent-config.ymlファイルの例を示します:

# Custom Docker image
image: python:3.11

# Setup script to run before the flow
setup_script:
  - apt-get update && apt-get install -y build-essential
  - pip install --upgrade pip
  - pip install -r requirements.txt

# Cache configuration
cache:
  key:
    files:
      - requirements.txt
      - Pipfile.lock
    prefix: python-deps
  paths:
    - .cache/pip
    - venv/

# Network configuration
network_policy:
  include_recommended_allowed: true
  allow_all_unix_sockets: true
  allowed_domains:
    - vault.example.com
  denied_domains:
    - malicious.com

# ID tokens for OIDC authentication
id_tokens:
  VAULT_ID_TOKEN:
    aud: https://vault.example.com

この設定では:

Python 3.11をベースイメージとして使用します。
フローの実行前に、ビルドツールおよびPythonの依存関係をインストールします。
pipおよび仮想環境のディレクトリをキャッシュします。
requirements.txtまたはPipfile.lockが変更されたときに、python-depsのプレフィックスを使用して新しいキャッシュを作成します。
HashiCorp VaultによるOIDC認証用のVAULT_ID_TOKEN IDトークンを提供します。

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

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

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

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

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

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

例:

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

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

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