Crea tu propia canalización de CI/CD.

Consulta y archiva la fuente de tu agente.

Seleccione la confirmación o rama que desea compilar y, a continuación, cree un archivo tar.gz de su directorio de agente. El motor de agentes de Atlas compila exactamente el archivo que usted carga, por lo que este paso determina el contenido de la compilación.

El siguiente ejemplo utiliza el comando tar para crear un archivo llamado agent.tar.gz. El ejemplo excluye los artefactos de desarrollo local del archivo, incluidos los directorios .venv, __pycache__ y .agentengine y el archivo .env.

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

Inicializa el archivo de compilación.

Antes de ejecutar los siguientes comandos, configure estas variables de entorno en su trabajo de 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>"

Utilice el ID del proyecto de su Atlas Agent Engine. Utilice el ID del espacio de trabajo devuelto por agentengine init. Establezca GATEWAY_HOST en el host de su entorno, como se indica en la tabla anterior. Almacene la clave API en el almacén de secretos de su sistema CI/CD y expóngala como CI_API_KEY. Establezca COMMIT_SHA en la confirmación que pase en git_info.commit_sha.

Para crear un registro de compilación y obtener una URL pre-firmada para la carga de código fuente, envíe una solicitud POST al punto final builds/archive-init ejecutando el siguiente comando curl:

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

Todos los campos del cuerpo de la solicitud son opcionales. Para que la compilación sea reproducible, siempre incluya la propiedad git_info.commit_sha. De lo contrario, el motor del agente Atlas etiquetará la imagen resultante como build-<random-id> en lugar de sha-<commit-sha>.

Para que la compilación se implemente correctamente y se omita el paso final, establezca auto_deploy en true.

Si la solicitud tiene éxito, el punto final devuelve una respuesta 201 Created similar a la siguiente:

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

Sube el código fuente del agente.

Para cargar el directorio de su agente, envíe una solicitud PUT que incluya el archivo como un archivo tar.gz al valor upload_url devuelto en el paso anterior ejecutando el siguiente comando curl:

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

No envíe una cabecera Authorization en esta solicitud. La URL prefirmada es la credencial y caduca en el momento indicado por el valor upload_expires_at devuelto por archive-init. Si la URL de carga caduca antes de que la utilice, vuelva a llamar a archive-init para obtener una nueva URL de carga.

Si la carga se realiza correctamente, el punto final devuelve una respuesta 200 OK.

Iniciar la construcción.

Para confirmar que la carga llegó y poner en cola el trabajo de compilación, envíe una solicitud POST sin cuerpo al punto final builds/<build-id>/start y guarde la respuesta ejecutando el siguiente comando 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"

Si la solicitud tiene éxito, el punto final devuelve una respuesta 202 Accepted similar a la siguiente:

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

Si ya se está ejecutando una compilación para la misma confirmación, este punto final devuelve un error 409 BUILD_ALREADY_ACTIVE. El error es una advertencia de compilación duplicada, no un fallo transitorio.

Cuando esté disponible, la respuesta incluye el ID y el estado de la compilación activa en el objeto details:

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

Establezca BUILD_ID al valor details.existing_build_id y consulte esa compilación en lugar de inicializar otro archivo de compilación:

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

Si la respuesta no incluye existing_build_id, enumere las compilaciones del espacio de trabajo y seleccione la compilación activa para la misma confirmación:

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)

Consultar el estado de la compilación.

Para esperar a que finalice la compilación, sondee el punto final builds/<build-id> a intervalos regulares hasta que la compilación alcance un estado terminal. El siguiente ejemplo sondea cada cinco segundos y detiene la canalización después de 30 minutos, de modo que una compilación atascada en el estado queued o waiting no pueda mantener su trabajo de CI/CD ejecutándose indefinidamente:

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

Cuando la compilación llega a succeeded, el bucle finaliza y la canalización continúa con el siguiente paso. Cuando llega a failed o cancelled, o cuando se agota el tiempo de espera, el ejemplo finaliza con un estado distinto de cero, por lo que la canalización falla. Ajuste TIMEOUT_SECONDS y INTERVAL_SECONDS para que coincidan con la duración de la compilación y la tolerancia de su sistema CI/CD a las llamadas a la API.

Mientras se realiza la compilación, el punto final devuelve una respuesta similar a la siguiente:

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

La siguiente tabla describe los valores status:

El campo lockfile_mode indica si el motor del agente Atlas respetó un archivo de bloqueo confirmado. Para obtener más información, consulte Gestionar dependencias.

Despliega la compilación.

Para desplegar la imagen que produjo la compilación, envíe una solicitud POST al punto final deployments ejecutando el siguiente comando curl:

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

El campo build_id es opcional. Si lo omite, el motor del agente de Atlas implementará la compilación exitosa más reciente en el espacio de trabajo.

Si la solicitud tiene éxito, el punto final devuelve una respuesta 202 Accepted similar a la siguiente:

{ "deployment_id": "deploy-abc123" }

La respuesta solo confirma que el motor del agente de Atlas aceptó la implementación. Para confirmar que la implementación se está ejecutando correctamente, consulte el punto final deployments/current, como se muestra en el siguiente ejemplo:

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

El punto final devuelve la implementación activa del espacio de trabajo, incluyendo su estado, la disponibilidad de cada componente que ejecuta la implementación y el estado general de la misma. La siguiente respuesta se recorta a los campos que necesita una comprobación mediante script:

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

En una implementación saludable, status es successful, cada entrada en el array components tiene available establecido en true con ready_replicas igual a replicas, y el campo available del objeto health es true.