独自の CI/CD パイプラインから構築

エージェントソースをチェックアウトしてアーカイブします。

ビルドするコミットまたはブランチをチェックアウトし、エージェントディレクトリの tar.gz アーカイブを作成します。 Atlas Agent Engine はアップロードしたアーカイブを正確にビルドするため、このステップはビルドに含まれる内容を決定します。

次の例では、tar コマンドを使用して agent.tar.gz という名前のアーカイブを作成します。この例では、.venv、__pycache__、.agentengine ディレクトリや .envファイルなどのローカル開発アーティファクトはアーカイブから除外されています。

tar --exclude='.venv' --exclude='__pycache__' \
  --exclude='.agentengine' --exclude='.env' \
  -czf agent.tar.gz -C <agent-directory> .

ビルド アーカイブを初期化します。

次のコマンドを実行中前に、 CI/CDジョブでこれらの環境変数を設定します。

export PROJECT_ID="<project-id>"
export WORKSPACE_ID="<workspace-id>"
export GATEWAY_HOST="agentengine-qa.mongodb.com"
export API_KEY="$CI_API_KEY"
export COMMIT_SHA="<commit-sha>"

Atlas Agent EngineプロジェクトのプロジェクトIDを使用します。 agentengine init によって返されたワークスペースIDを使用します。上記表に記載されているように、環境のホストに GATEWAY_HOST を設定します。 APIキーを CI / CD システムのシークレット ストアに保存し、CI_API_KEY として公開します。 git_info.commit_sha で渡すコミットに COMMIT_SHA を設定します。

ビルドレコードを作成し、ソース アップロード用の署名付きURLを取得するには、次の curl コマンドを実行中て builds/archive-init エンドポイントに POSTリクエストを送信します。

curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/archive-init" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
        "label": "my-ci-build-123",
        "git_info": {
          "commit_sha": "<commit-sha>",
          "branch": "<branch-name>",
          "dirty": false
        },
        "build_target": { "subdirectory": "" },
        "auto_deploy": false
      }'

リクエスト本文のフィールドはすべてオプションです。ビルドを再現可能にするには、常に git_info.commit_shaプロパティを渡します。指定しない場合、Atlas エージェント エンジンは結果のイメージを sha-<commit-sha> ではなく build-<random-id> にタグ付けします。

ビルドが自分自身を成功させ、最後のステップをスキップするには、auto_deploy を true に設定します。

リクエストが成功すると、エンドポイントは次のような 201 Created 応答を返します。

{
  "build_id": "bld_01ABC...",
  "upload_url": "https://<presigned-s3-url>",
  "upload_expires_at": "2026-01-01T00:05:00Z",
  "source_type": "archive"
}

エージェントソースをアップロードします。

エージェントディレクトリをアップロードするには、次の curl コマンドを実行中して、前のステップから返された upload_url 値に、アーカイブを tar.gzファイルとして含む PUTリクエストを送信します。

curl -s -X PUT \
  --upload-file agent.tar.gz \
  -H "Content-Type: application/gzip" \
  "$UPLOAD_URL"

このリクエストでは Authorization ヘッダーを送信しないでください。署名付きURL は認証情報であり、archive-init によって返される upload_expires_at 値で指定された時点で期限切れになります。アップロードURL が使用前に期限切れになった場合は、archive-init を再度呼び出して新しいアップロードURLを取得します。

アップロードが成功すると、エンドポイントは 200 OK 応答を返します。

ビルドを開始します。

アップロードが到達したことを確認し、ビルドジョブをキューにするには、 本文を指定せずに POSTリクエストをbuilds/<build-id>/start エンドポイントに送信し、次の curl コマンドを実行中て応答を保存します。

RESPONSE=$(curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/$BUILD_ID/start" \
  -H "Authorization: Bearer $API_KEY")
echo "$RESPONSE"

リクエストが成功すると、エンドポイントは次のような 202 Accepted 応答を返します。

{ "build_id": "bld_01ABC...", "status": "accepted" }

同じコミットのビルドがすでに実行中の 場合、このエンドポイントは 409 BUILD_ALREADY_ACTIVE エラーを返します。エラーは一時的な障害ではなく、重複ビルド 保護です。

使用可能な場合、レスポンスには detailsオブジェクト内のアクティブなビルドのIDとステータスが含まれます。

{
  "success": false,
  "code": "BUILD_ALREADY_ACTIVE",
  "details": {
    "existing_build_id": "bld_01ABC...",
    "existing_status": "in_progress"
  }
}

BUILD_ID を details.existing_build_id の値に設定し、別のビルド アーカイブを初期化する代わりにそのビルドをポーリングします。

BUILD_ID=$(printf '%s' "$RESPONSE" |
  jq -r '.details.existing_build_id // empty')

レスポンスに existing_build_id が含まれていない場合は、ワークスペース ビルドを一覧表示して、同じコミットのアクティブなビルドを選択します。

BUILD_ID=$(curl -s \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds?limit=100" \
  -H "Authorization: Bearer $API_KEY" |
  jq -r --arg commit "$COMMIT_SHA" '
    .builds[]
    | select(.commit_sha == $commit)
    | select(
        .status == "queued" or
        .status == "in_progress" or
        .status == "waiting"
      )
    | .build_id' |
  head -n 1)

ビルド ステータスをポーリングします。

ビルドが完了するのを待つには、ビルドがターミナルステータスに達するまで定期的に builds/<build-id> エンドポイントをポーリングします。次の例では5 秒ごとにポーリングし、30 分後にパイプラインを失敗させるため、queued または waiting 状態でビルドが停止した場合、CI/CDジョブを無期限に実行中続けることができなくなります。

TIMEOUT_SECONDS=1800
INTERVAL_SECONDS=5
ELAPSED=0
while true; do
  STATUS=$(curl -s \
    "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/builds/$BUILD_ID" \
    -H "Authorization: Bearer $API_KEY" \
    | jq -r '.status')
  if [ "$STATUS" = "succeeded" ]; then
    break
  elif [ "$STATUS" = "failed" ] || [ "$STATUS" = "cancelled" ]; then
    echo "Build $BUILD_ID ended with status: $STATUS" >&2
    exit 1
  elif [ "$ELAPSED" -ge "$TIMEOUT_SECONDS" ]; then
    echo "Timed out after ${TIMEOUT_SECONDS}s waiting for build $BUILD_ID" >&2
    exit 1
  fi
  sleep "$INTERVAL_SECONDS"
  ELAPSED=$((ELAPSED + INTERVAL_SECONDS))
done

ビルドが succeeded に達すると、ループは終了し、パイプラインは次のステップに進みます。 failed または cancelled に達したとき、またはタイムアウトが経過すると、例はゼロ以外のステータスで終了するため、パイプラインは失敗します。 API呼び出しに対するビルド期間と CI/CD システムの許容度に一致するように TIMEOUT_SECONDS と INTERVAL_SECONDS を調整します。

ビルドの進行中、エンドポイントは次のような応答を返します。

{
  "build_id": "bld_01ABC...",
  "status": "in_progress",
  "executor_type": "vm",
  "image_uri": null,
  "lockfile_mode": null,
  "error_message": null
}

以下の表では、status 値について説明しています。

lockfile_modeフィールドは、Atlas Agent Engine がコミットされたロックファイルを尊重したかどうかを報告します。詳細については、「 依存関係の管理 」を参照してください。

ビルドを配置します。

ビルドによって生成されたイメージを配置するには、次の curl コマンドを実行中て deployments エンドポイントに POSTリクエストを送信します。

curl -s -X POST \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/deployments" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "build_id": "'"$BUILD_ID"'" }'

build_idフィールドは任意です。省略すると、Atlas Agent Engine はワークスペースに最新の成功したビルドを配置します。

リクエストが成功すると、エンドポイントは次のような 202 Accepted 応答を返します。

{ "deployment_id": "deploy-abc123" }

応答は、Atlas Agent Engine が配置を受け入れたことを確認します。配置が正しく実行中いることを確認するには、次の例に示すように、deployments/current エンドポイントをポーリングします。

curl -s \
  "https://$GATEWAY_HOST/api/v1/projects/$PROJECT_ID/workspaces/$WORKSPACE_ID/deployments/current" \
  -H "Authorization: Bearer $API_KEY"

エンドポイントは、ステータス、配置で実行される各コンポーネントの準備状況、配置の全体的な健全性など、ワークスペースのアクティブな配置を返します。次の応答は、スクリプト化されたチェックに必要なフィールドに削除されます。

{
  "deployment_id": "deploy-abc123",
  "status": "successful",
  "components": [
    {
      "name": "agent",
      "available": true,
      "replicas": 1,
      "ready_replicas": 1
    }
  ],
  "health": {
    "available": true,
    "checked_at": "2026-01-01T00:10:00Z"
  }
}

正常な配置では、status は successful で、components 配列のすべてのエントリには available が true に設定され、ready_replicas は replicas に等しく、かつ health オブジェクトの availableフィールドはは true です。