フロー実行を設定する

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

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

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

フローのセキュリティ

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

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

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

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

Executorアーキテクチャ

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

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

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

CI/CD実行を設定する

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

設定ファイルを作成する

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

プロジェクトの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

カスタムイメージの要件

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

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

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

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

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

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

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

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

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

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

これらのコマンドは:

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

キャッシュを設定する

キャッシュを設定すると、実行間でファイルやディレクトリを保持することで、後続のフロー実行を高速化できます。キャッシュは、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変数をサポートしています。

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

利用可能なすべてのオプションを使用した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:
    - my-own-site.com
  denied_domains:
    - malicious.com

この設定では:

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

Runnerを設定する

CI/CDを使用するフローは、Runnerで実行されます。これらのRunnerは、次の条件を満たす必要があります:

• Dockerイメージをサポートするexecutorを使用していること。たとえば、docker、docker-autoscaler、kubernetesなどが該当します。shell executorはサポートされていません。
• Runnerが適切なジョブを選択できるように、gitlab--duoタグが存在すること。
• インスタンスRunnerであるか、トップレベルグループに割り当てられていること。フローでは、サブグループまたはプロジェクト用に設定されたRunnerは使用できません。GitLab Self-Managedでは、duo_runner_restrictions FFを無効にすることで、この制限を無効にできます。

さらに、GitLab Self-ManagedのRunnerでは次の条件があります:

• GitLabインスタンス用に設定されたGitLab Duo Agent Platformサービスへのネットワークトラフィックを許可する必要があります。
  • GitLab Duo Agent PlatformサービスにはAIゲートウェイが付属しています。ご自身でAIゲートウェイをホストし、Agent PlatformのローカルURLを設定しない場合、エージェント型機能はduo-workflow-svc.runway.gitlab.netのポート443にトラフィックをルーティングします。
• registry.gitlab.comからデフォルトのイメージをダウンロードできること、または指定したDockerイメージにアクセスできること。

証明書チェーンに自己署名証明書を含むGitLabインスタンスの場合、GitLab Duo CLIには追加の設定が必要です。

GitLab.comでは、フローは以下を使用できます:

• GitLabが提供するホストRunner。

Runnerで実行されるフローは、ネットワークとファイルシステムの分離を実現するランタイムサンドボックスによって保護できます。サンドボックスのメリットを享受するには、次の条件を満たす必要があります:

1. Runnerの設定でprivileged = trueを指定し、特権モードを有効にすること。
2. 以下のいずれかを使用します。
   • GitLab Duo Agent PlatformのデフォルトDockerベースイメージ
   • A SRTがインストールされたカスタムイメージ

Runnerの特権モード

環境サンドボックス保護を使用する場合、特権モードが必要です。これは、デフォルトのGitLabが提供するイメージ、またはSRTがインストールされたカスタムイメージを使用する場合に適用されます。SRTなしでカスタムDockerイメージを使用する場合、サンドボックスは適用できないため、特権モードは必要ありません。