빌드 API

프로젝트에서 현재 접속 가능한 주소를 한 목록으로 반환합니다. 기본 URL과 연결된 커스텀 도메인이 포함됩니다.

{
  "endpoints": [
    "https://abc123.justdeploy.site",
    "https://www.example.com"
  ]
}

최신 빌드부터 반환합니다. 한 번에 받을 개수는 limit(1~100, 기본값 50)으로 정합니다. 다음 페이지를 가져올 때는 이전 응답의 nextCursor를 cursor로 보내고, null이 반환되면 조회를 끝내세요.

{
  "builds": [
    {
      "id": "b1234567-abcd-...",
      "title": "Add password reset email",
      "description": "Adds the reset flow and the SES template.",
      "commit": null,
      "version": null,
      "runtime": "nodejs22.x",
      "size": 524288,
      "status": "ready",
      "error": null,
      "suggestion": null,
      "isLive": true,
      "canRedeploy": false,
      "createdAt": "2026-03-20T...",
      "updatedAt": "2026-03-20T..."
    }
  ],
  "nextCursor": null,
  "redeployAvailability": { "status": "available" }
}

isLive는 프로젝트가 실제로 서비스 중인 빌드를 나타냅니다. 보통은 가장 최신 빌드라서 불필요해 보이지만, 배포가 헬스 체크에 실패해 플랫폼이 롤백하면 최신 빌드와 실행 중인 빌드가 달라집니다. 목록 맨 위를 실행 중이라고 가정하지 말고 이 값을 확인하세요.

완료된 빌드의 값만 신뢰하세요. 헬스 체크 전에 이미지가 교체되므로 아직 deploying 상태인 빌드도 실행 중으로 표시되지만 이후 롤백될 수 있습니다. 상태가 ready 또는 error가 아니면 isLive를 무시하세요.

false는 실행 중이 아니라는 뜻뿐 아니라 현재 배포 정보를 확인하지 못했다는 뜻일 수도 있습니다. 플랫폼이 배포 정보를 읽지 못하면 요청 전체를 실패시키는 대신 해당 페이지의 값을 모두 false로 표시합니다. 따라서 목록에 실행 중인 빌드가 없더라도 실제 서비스가 중단됐다고 단정하면 안 됩니다.

canRedeploy는 아래 Redeploy API가 허용하는 빌드인지 알려줍니다. 현재 배포된 빌드를 제외한 최근 성공 빌드 10개만 대상입니다. 응답의 다른 필드만으로는 재배포 가능 여부를 정확히 알 수 없으므로 status를 조합해 판단하지 말고 이 값을 사용하세요.

redeployAvailability는 재배포 후보가 없는 두 상황을 구분합니다. "available"이면 재배포 가능한 항목이 없더라도 목록 자체가 정확한 결과입니다. "temporarily_unavailable"이면 플랫폼이 배포된 대상을 읽지 못한 상태로, 모든 isLive와 canRedeploy가 false가 됩니다. 이 경우 retryAfter에 지정된 시간만큼 기다린 뒤 다시 시도하세요.

새 빌드를 생성하고 앱 코드 .zip 파일을 올릴 presigned URL을 반환합니다.

본문과 본문의 모든 필드는 선택 항목입니다. 이 빌드가 무엇을 변경하는지 알리려면 title과 description을 보내세요. 이 값은 상태와 시간만 보이는 콘솔 빌드 목록에 표시됩니다. 커밋 메시지처럼 title에 한 줄 요약(최대 128자), description에 상세 내용(최대 4096자)을 적으세요. 제한을 넘으면 400이 반환되고, 두 값은 앞뒤 공백이 제거되며 빈 문자열은 null로 저장됩니다.

{
  "title": "Add password reset email",
  "description": "Adds the reset flow and the SES template. Needed before launch."
}

{
  "build": {
    "id": "b2345678-efgh-...",
    "title": "Add password reset email",
    "description": "Adds the reset flow and the SES template. Needed before launch.",
    "commit": null,
    "version": null,
    "runtime": null,
    "size": null,
    "status": "pending",
    "error": null,
    "suggestion": null,
    "createdAt": "2026-03-20T...",
    "updatedAt": "2026-03-20T..."
  },
  "url": "https://upload.justdeploy.net/..." // Presigned upload URL
}

발급받은 presigned URL로 zip 파일을 업로드하세요.

curl -X PUT "$UPLOAD_URL" \
  -H "Content-Type: application/zip" \
  --data-binary @app.zip

해당 프로젝트의 빌드가 이미 진행 중이면 요청은 기존 빌드와 함께 409 Conflict를 반환합니다. 그 빌드의 상태를 다시 조회하고 완료되면 재시도하세요.

{
  "status": "Conflict",
  "message": "A build is already in progress for this project.",
  "build": {
    "id": "b1234567-abcd-...",
    "status": "building",
    "createdAt": "2026-05-05T..."
  }
}

빌드 상태를 확인합니다. ready 또는 error가 될 때까지 이 API를 주기적으로 조회하세요. 이를 polling이라고 합니다.

{
  "build": {
    "id": "b2345678-efgh-...",
    "title": "Add password reset email",
    "description": "Adds the reset flow and the SES template.",
    "commit": null,
    "version": null,
    "runtime": "nodejs22.x",
    "size": 524288,
    "status": "ready",
    "error": null,
    "suggestion": "Consider committing a lock file so future builds stay reproducible.",
    "warning": null,
    "canceledAt": null,
    "isLive": true,
    "createdAt": "2026-03-20T...",
    "updatedAt": "2026-03-20T..."
  }
}

성공하면 suggestion에 개선 안내(누락된 lock 파일, 개발용 시작 명령, 하드코딩된 URL, 소스에 커밋된 secret)가 포함될 수 있으며 보통 null입니다. 오류가 아니며 배포를 차단하지 않습니다. 내용을 읽고 이것만을 위해 다시 빌드하지 말고 다음 코드 변경에 반영하세요.

warning은 다릅니다. 배포가 실제로 작동하지 않을 수 있다는 뜻이며 상태가 ready여도 나타날 수 있습니다. 헬스 체크는 작동하는 페이지가 아니라 어떤 응답이든 허용하므로 라우트가 없는 앱도 성공으로 끝날 수 있습니다. 배포가 성공했다고 알리기 전에 반드시 확인하세요.

상태가 어떻게 표시되든 canceledAt이 설정되면 주기적 조회를 멈추세요. 아래 설명을 참고하세요.

isLive는 빌드가 끝난 뒤에만 계산되므로 상태를 조회하는 동안에는 계속 false입니다. 최종 상태가 나오기 전에는 이를 “배포되지 않음”으로 해석하지 마세요.

현재 환경 변수로 프로젝트가 실행 중인 소스를 빌드하고 결과를 배포합니다. 업로드, 본문, 별도 배포 단계가 필요하지 않으며 배포 범위 키가 필요합니다.

환경 변수를 변경했을 때 사용하는 방법입니다. 변수는 빌드할 때 이미지에 포함되므로 값을 수정해도 다시 빌드하기 전까지 실행 중인 앱은 기존 값을 사용합니다. 새 값을 적용하기 위해 변경되지 않은 소스를 다시 zip으로 묶는 것은 불필요한 작업입니다.

선택할 빌드는 없습니다. 항상 현재 배포된 소스를 재빌드합니다. 이전 소스로 돌아가려면 아래 redeploy 엔드포인트를 사용하세요.

새 빌드는 같은 소스로 만들어지므로 여기와 아래 redeploy 모두 복사하는 빌드의 title과 description을 물려받습니다.

{
  "build": {
    "id": "b3456789-ijkl-...",
    "status": "pending",
    "title": "Add password reset email",
    "description": "Adds the reset flow and the SES template.",
    ...
  }
}

POST /builds 후와 같은 방식으로 새 빌드 상태를 주기적으로 조회하세요. 다른 빌드가 실행 중이거나 성공한 배포가 없거나 현재 배포된 빌드가 성공 상태가 아니면 409, 원본 소스 파일이 사라졌으면 410이 반환됩니다. 503은 플랫폼이 현재 배포 정보를 확인하지 못한 일시적 오류일 수 있으므로 다시 시도하세요.

이전 빌드를 만든 소스로 해당 버전을 다시 배포합니다. canRedeploy가 true인 빌드의 id를 전달하세요. 본문은 없으며 배포 범위 키가 필요합니다.

세 작업을 구분하세요. Rebuild는 현재 서비스 중인 소스를 현재 환경 변수로 다시 빌드합니다. Redeploy는 고객이 선택한 이전 소스를 새로 빌드해 배포합니다. 자동 rollback은 새 배포가 헬스 체크에 실패했을 때 플랫폼이 직전 이미지로 되돌리는 동작입니다. 실제로 이전 이미지를 즉시 복구하는 것은 rollback뿐이므로 이 API의 이름은 rollback이 아니라 Redeploy입니다.

기존 결과로 즉시 되돌리는 작업은 아닙니다. 선택한 빌드의 원본 소스를 새 빌드로 복사한 뒤 전체 배포 과정을 다시 실행합니다. 따라서 일반 빌드와 같은 시간과 비용이 들며, 과거에 성공했던 소스도 이번에는 실패할 수 있습니다.

두 가지는 의도적으로 현재 상태를 유지합니다. 환경 변수는 이전 빌드가 실행될 때의 값이 아니라 새 분석이 시작할 때 읽은 현재 값을 사용합니다. 당시 앱의 런타임 인증 정보도 복구되지 않으므로 이후 폐기된 키는 계속 폐기 상태입니다. 이전 소스가 변경된 변수에 의존한다면 먼저 GET /environments를 확인하세요.

{
  "build": {
    "id": "b4567890-mnop-...",
    "status": "pending",
    "title": "Add password reset email",
    "description": "Adds the reset flow and the SES template.",
    ...
  }
}

POST /builds 후와 같은 방식으로 새 빌드 상태를 주기적으로 조회하세요. 빌드가 이 프로젝트의 것이 아니면 404가 반환됩니다. 다른 빌드가 실행 중이거나, 대상 빌드가 실패·취소됐거나, 이미 배포된 빌드이거나, 최근 재배포 가능한 10개에서 벗어났다면 409가 반환됩니다. 원본 소스 파일이 없으면 410이므로 다른 빌드를 선택하세요. 503은 현재 배포 정보를 확인하지 못한 일시적 오류일 수 있으므로 다시 시도하세요.

아직 진행 중인 빌드를 중지합니다. 배포 범위 키가 필요합니다.

프로세스를 즉시 종료하는 대신 빌드에 중지 표시를 합니다. 현재 실행 중인 단계는 완료됩니다. 분석 호출은 끝까지 실행되고, 이미 시작된 컨테이너 빌드는 이미지를 생성합니다. 그다음 단계 경계에서 빌드가 중단됩니다. 따라서 analyzing 중 멈추면 빌드 단계 자체가 시작되지 않아 가장 많이 절약됩니다.

빌드에 중지 표시가 되는 즉시 프로젝트 잠금이 풀립니다. 중지된 빌드가 완전히 끝날 때까지 기다리지 않고 바로 새 빌드를 만들 수 있습니다.

{
  "build": {
    "id": "b2345678-efgh-...",
    "status": "building",
    "canceledAt": "2026-03-20T...",
    ...
  }
}

status는 덮어쓰지 않고 빌드가 멈춘 단계에 그대로 남습니다. 따라서 진행 정도를 알 수 있습니다. analyzing이면 아무것도 빌드되지 않았고, building이면 이미지가 생성되었으며, error이면 어차피 실패할 빌드였다는 뜻입니다. canceledAt이 있는 빌드는 모두 종료된 것으로 처리하세요.

이미 취소된 빌드를 다시 취소하면 200을 반환합니다. 409는 더 이상 멈출 수 없다는 뜻입니다. 이미 완료되었거나 이미지 교체와 헬스 체크가 실행 중인 deploying에 도달한 경우입니다. 이 단계에서 개입하면 깨진 이미지가 서비스될 수 있습니다.