자체 CI/CD 파이프라인에서 구축

에이전트 소스를 확인하고 보관합니다.

빌드 하려는 커밋 또는 브랜치를 확인한 다음 에이전트 디렉토리 의 tar.gz 아카이브를 생성합니다. Atlas Agent 엔진은 업로드한 아카이브를 정확히 빌드하므로 이 단계에서 빌드 에 포함할 내용을 결정합니다.

다음 예시 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로 노출합니다. COMMIT_SHA를 git_info.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 Agent Engine이 결과 이미지에 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에 도달하거나 시간 제한이 경과하면 0이 아닌 상태로 예시 가 종료되어 파이프라인 실패합니다. 빌드 기간과 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 엔진이 작업 공간에서 가장 최근에 성공적인 빌드 배포합니다.

요청 성공하면 엔드포인트는 다음과 유사한 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입니다.