Build from Your Own CI/CD Pipeline

Check out and archive your agent source.

Check out the commit or branch that you want to build, then create a tar.gz archive of your agent directory. The Atlas Agent Engine builds exactly the archive that you upload, so this step determines what the build contains.

The following example uses the tar command to create an archive named agent.tar.gz. The example excludes local development artifacts from the archive, including the .venv, __pycache__, and .agentengine directories and the .env file.

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

Initialize the build archive.

Before running the following commands, set these environment variables in your CI/CD job:

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>"

Use the project ID for your Atlas Agent Engine project. Use the workspace ID returned by agentengine init. Set GATEWAY_HOST to the host for your environment, as listed in the table above. Store the API key in your CI/CD system's secret store and expose it as CI_API_KEY. Set COMMIT_SHA to the commit that you pass in git_info.commit_sha.

To create a build record and get a presigned URL for the source upload, send a POST request to the builds/archive-init endpoint by running the following curl command:

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
      }'

All fields in the request body are optional. To make the build reproducible, always pass the git_info.commit_sha property. Without it, the Atlas Agent Engine tags the resulting image build-<random-id> instead of sha-<commit-sha>.

To have a successful build deploy itself and skip the final step, set auto_deploy to true.

If the request succeeds, the endpoint returns a 201 Created response that resembles the following:

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

Upload the agent source.

To upload your agent directory, send a PUT request that includes the archive as a tar.gz file to the upload_url value returned from the preceding step by running the following curl command:

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

Do not send an Authorization header on this request. The presigned URL is the credential, and it expires at the time given by the upload_expires_at value returned by archive-init. If the upload URL expires before you use it, call archive-init again to get a new upload URL.

If the upload succeeds, the endpoint returns a 200 OK response.

Start the build.

To confirm that the upload arrived and to queue the build job, send a POST request with no body to the builds/<build-id>/start endpoint and save the response by running the following curl command:

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"

If the request succeeds, the endpoint returns a 202 Accepted response that resembles the following:

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

If a build for the same commit is already running, this endpoint returns a 409 BUILD_ALREADY_ACTIVE error. The error is a duplicate build guard rather than a transient failure.

When available, the response includes the ID and status of the active build in the details object:

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

Set BUILD_ID to the details.existing_build_id value and poll that build instead of initializing another build archive:

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

If the response does not include existing_build_id, list the workspace builds and select the active build for the same commit:

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)

Poll the build status.

To wait for the build to finish, poll the builds/<build-id> endpoint on a regular interval until the build reaches a terminal status. The following example polls every five seconds and fails the pipeline after 30 minutes, so that a build stuck in the queued or waiting state can't keep your CI/CD job running indefinitely:

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

When the build reaches succeeded, the loop exits and the pipeline continues to the next step. When it reaches failed or cancelled, or when the timeout elapses, the example exits with a nonzero status so the pipeline fails. Adjust TIMEOUT_SECONDS and INTERVAL_SECONDS to match your build duration and your CI/CD system's tolerance for API calls.

While the build is in progress, the endpoint returns a response that resembles the following:

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

The following table describes the status values:

The lockfile_mode field reports whether the Atlas Agent Engine honored a committed lock file. To learn more, see Manage Dependencies.

Deploy the build.

To deploy the image that the build produced, send a POST request to the deployments endpoint by running the following curl command:

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"'" }'

The build_id field is optional. If you omit it, the Atlas Agent Engine deploys the most recent successful build in the workspace.

If the request succeeds, the endpoint returns a 202 Accepted response that resembles the following:

{ "deployment_id": "deploy-abc123" }

The response confirms only that the Atlas Agent Engine accepted the deployment. To confirm that the deployment is running correctly, poll the deployments/current endpoint, as shown in the following example:

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

The endpoint returns the workspace's active deployment, including its status, the readiness of each component that the deployment runs, and the deployment's overall health. The following response is trimmed to the fields that a scripted check needs:

{
  "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"
  }
}

In a healthy deployment, status is successful, every entry in the components array has available set to true with ready_replicas equal to replicas, and the health object's available field is true.