フロー実行を設定する

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

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

CI/CDを使用してフローを実行する環境を設定できます。独自のRunnerを使用することもできます。

フローのセキュリティ

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

アクセスを制限するために、コンポジットIDを使用します。
それらが自由に使用できるツールは、フローの目的に固有のものです。これらのツールには、マージリクエストの作成、または実行環境でのローカルShellコマンドの実行が含まれます。

デフォルトでは、Runner環境はGitLabインスタンスへのネットワークアクセスのみを許可しますが、これを変更できます。この分離された環境は、Shellコマンドの実行による意図しない結果から保護します。

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

CI/CDの実行を設定する

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

設定ファイルを作成する

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

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

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

デフォルトでは、CI/CDで実行されるすべてのフローは、GitLabが提供する標準のDockerイメージを使用します。このDockerイメージには、Anthropic Sandbox Runtime（srt）を使用することにより、ネットワーク保護が自動的に含まれています。このイメージは、GitLabインスタンスへのアクセスのみを許可するように設定されています。ただし、Dockerイメージを変更して、独自のイメージを代わりに指定できます。独自のイメージは、特定の依存関係またはツールを必要とする複雑なプロジェクトに役立ちます。これを行うと、エージェントはセッションに関連付けられているGitLab Runnerから到達可能な任意のドメインに到達できるようになります。

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

image: YOUR_DOCKER_IMAGE

例:

image: python:3.11-slim

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

image: node:20-alpine

カスタムイメージの要件

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

git
npm

ほとんどのベースイメージには、デフォルトでこれらのコマンドが含まれています。ただし、最小限のイメージ（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/

この設定では:

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

Runnerを設定する

CI/CDを使用するフローは、Runnerで実行されます。これらのRunnerは、以下を行う必要があります:

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

さらに、GitLabセルフマネージドのRunner:

GitLabインスタンス用に設定されたGitLab Duoワークフローサービスへのネットワークトラフィックを許可する必要があります。カスタムモデルを使用していない場合、このトラフィックはポート443のduo-workflow-svc.runway.gitlab.netに送信されます。
registry.gitlab.comからデフォルトのイメージをダウンロードできるか、指定したDockerイメージにアクセスできる必要があります。
フローの内容によっては、特権が必要になる場合があります。たとえば、Dockerイメージをビルドするフローには、特権Runnerが必要です。

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

ホストされたRunner、GitLabが提供します。

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

特権モードを有効にするには、Runnerの設定でprivileged = trueを設定します。
GitLab Duo Agent Platformのデフォルトのベースイメージイメージを使用します。