deployments

배포 트리거·상태·취소·롤백·로그·진단·git 연결

24 operations — 배포 트리거·상태·취소·롤백·로그·진단·git 연결

`GET /api/v1/apps/{appID}/deployments`

deployGetApiV1AppsByAppIDDeployments

앱의 배포 이력을 최신순으로 반환한다.

호출 권한: 인증된 사용자 (RequireAuth).
limit 은 1~100 (default 20). offset 은 0 이상.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDDeployments(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDDeployments(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDDeploymentsAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDDeployments(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_deployments(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_deployments(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDDeployments", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Query 파라미터 — query 로 전달 (문자열 값)

이름	타입	설명
`limit`	integer	페이지 크기 (1~100, 기본 20)
`offset`	integer	offset (기본 0)

응답 — 200 · 배포 목록

이름	타입	설명
`items`	array<object>
`nextCursor` (wire: `next_cursor`)	string
`total`	integer

에러 status: 400 401 500 — 에러 처리

`POST /api/v1/apps/{appID}/deployments`

deployPostApiV1AppsByAppIDDeployments

앱 owner / 테넌트 admin / platform admin 이 수동으로 새 배포를 시작한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
commit_sha 가 비어있으면 GitConnection 의 default branch HEAD 를 사용. force_rebuild=true 면 동일 sha 가 빌드돼 있어도 재빌드.
사전 조건: 앱에 subdomain 이 설정돼 있어야 하고 (없으면 412), GitConnection 이 등록돼 있어야 한다 (없으면 412). 이미 진행 중인 배포가 있으면 409. 심사 승인(공개)된 앱은 스테이징을 켜야 배포 가능 (미옵트인이면 412 staging_required — prod 반영은 심사 promote 만, spec 016 FR-023).
부수 효과: 새 deployment row 생성 (status=pending) + 빌드 orchestrator 큐잉 + 도메인 이벤트 발행.

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1AppsByAppIDDeployments(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1AppsByAppIDDeployments(pathParams, query, body)` — 비동기: `deployPostApiV1AppsByAppIDDeploymentsAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1AppsByAppIDDeployments(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_apps_by_app_id_deployments(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_apps_by_app_id_deployments(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1AppsByAppIDDeployments", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`commit_sha`	string	CommitSha 는 배포할 git commit (40자 hex). 비어있으면 GitConnection 의 default branch HEAD 를 자동으로 가져온다.
`force_rebuild`	boolean	ForceRebuild 가 true 면 동일 commit_sha 가 이미 빌드돼 있어도 이미지를 새로 빌드한다. 의존성 갱신 / base image 변경 반영용.

응답 — 202 · 트리거된 배포

이름	타입	설명
`appId` (wire: `app_id`)	string	AppID 는 소속 앱 UUID.
`commitSha` (wire: `commit_sha`)	string	CommitSha 는 빌드된 git commit (40자 hex).
`completedAt` (wire: `completed_at`)	string	CompletedAt 은 배포 종료 시각. 종료 전엔 nil.
`currentStage` (wire: `current_stage`)	string	CurrentStage 는 진행 중인 stage 이름 (pending/building/pushing/deploying). 종료 상태에선 nil.
`failureReason` (wire: `failure_reason`)	any	FailureReason 은 실패 시의 상세. status != failed 면 nil.
`id`	string	ID 는 배포 UUID.
`imageUri` (wire: `image_uri`)	string	ImageURI 는 빌드 후 push 된 GCR 이미지 경로. 빌드 전엔 nil.
`startedAt` (wire: `started_at`)	string	StartedAt 은 배포 시작 시각 (RFC3339).
`status`	string	Status 는 배포 상태. 가능 값: pending / building / pushing / deploying / succeeded / failed / cancelled.
`triggerSource` (wire: `trigger_source`)	string	TriggerSource 는 배포 트리거 출처. 가능 값: webhook / manual / rollback.

에러 status: 400 401 403 404 409 412 500 — 에러 처리

`GET /api/v1/apps/{appID}/deployments/{did}`

deployGetApiV1AppsByAppIDDeploymentsByDid

특정 배포의 현재 상태와 상세를 반환한다.

호출 권한: 인증된 사용자 (RequireAuth).
진행 중 배포면 current_stage 가 채워져 있고 completed_at 은 nil.
실패 배포면 failure_reason 이 채워져 있다.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDDeploymentsByDid(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDDeploymentsByDid(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDDeploymentsByDidAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDDeploymentsByDid(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_deployments_by_did(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_deployments_by_did(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDDeploymentsByDid", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID
`did` 필수	string	배포 UUID

응답 — 200 · 배포 상세

이름	타입	설명
`appId` (wire: `app_id`)	string	AppID 는 소속 앱 UUID.
`commitSha` (wire: `commit_sha`)	string	CommitSha 는 빌드된 git commit (40자 hex).
`completedAt` (wire: `completed_at`)	string	CompletedAt 은 배포 종료 시각. 종료 전엔 nil.
`currentStage` (wire: `current_stage`)	string	CurrentStage 는 진행 중인 stage 이름 (pending/building/pushing/deploying). 종료 상태에선 nil.
`failureReason` (wire: `failure_reason`)	any	FailureReason 은 실패 시의 상세. status != failed 면 nil.
`id`	string	ID 는 배포 UUID.
`imageUri` (wire: `image_uri`)	string	ImageURI 는 빌드 후 push 된 GCR 이미지 경로. 빌드 전엔 nil.
`startedAt` (wire: `started_at`)	string	StartedAt 은 배포 시작 시각 (RFC3339).
`status`	string	Status 는 배포 상태. 가능 값: pending / building / pushing / deploying / succeeded / failed / cancelled.
`triggerSource` (wire: `trigger_source`)	string	TriggerSource 는 배포 트리거 출처. 가능 값: webhook / manual / rollback.

에러 status: 400 401 404 500 — 에러 처리

`POST /api/v1/apps/{appID}/deployments/{did}/cancel`

deployPostApiV1AppsByAppIDDeploymentsByDidCancel

진행 중 배포를 cancelled 로 전환해 in-progress 슬롯을 즉시 해제한다. stale worker 는 stage boundary 에서 terminal 상태를 보고 중단한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
이미 succeeded/failed 상태면 409, 이미 cancelled 상태면 idempotent 204.
부수 효과: deployment.status/current_stage/cancel_requested_at/completed_at 갱신.

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1AppsByAppIDDeploymentsByDidCancel(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1AppsByAppIDDeploymentsByDidCancel(pathParams, query, body)` — 비동기: `deployPostApiV1AppsByAppIDDeploymentsByDidCancelAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1AppsByAppIDDeploymentsByDidCancel(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_apps_by_app_id_deployments_by_did_cancel(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_apps_by_app_id_deployments_by_did_cancel(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1AppsByAppIDDeploymentsByDidCancel", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID
`did` 필수	string	배포 UUID

응답 — 204 · 취소 요청됨 (no content)

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 409 412 500 — 에러 처리

`POST /api/v1/apps/{appID}/deployments/{did}/rollback`

deployPostApiV1AppsByAppIDDeploymentsByDidRollback

지정한 (이미 빌드된) 배포의 이미지로 K8s 디플로이먼트를 갱신한다. 새 deployment row 는 만들지 않는다 — K8s 이미지 swap + prod 포인터 이벤트로 기록 (spec 016 D13).

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
사전 조건: source 배포에 image_uri 가 있어야 함 (없으면 412).
옵트인 앱 (spec 016 FR-014): 심사 승인 이력 있는 버전만 (403). rollback 은 스키마를 되돌리지 않음 — 삭제성 변경이 그 사이 반영됐으면 body 의 confirm_schema_skew=true 필수 (412).
실행 모델 (spec 016 D13): 가드 통과 시 즉시 202 — 적용은 비동기, 결과는 앱 상세의 production_deployment_id 로 확인.
부수 효과: K8s 이미지 swap + prod 포인터 갱신 이벤트.

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1AppsByAppIDDeploymentsByDidRollback(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1AppsByAppIDDeploymentsByDidRollback(pathParams, query, body)` — 비동기: `deployPostApiV1AppsByAppIDDeploymentsByDidRollbackAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1AppsByAppIDDeploymentsByDidRollback(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_apps_by_app_id_deployments_by_did_rollback(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_apps_by_app_id_deployments_by_did_rollback(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1AppsByAppIDDeploymentsByDidRollback", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID
`did` 필수	string	롤백 대상 (소스) 배포 UUID — 이 배포의 image_uri 를 사용

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`confirm_schema_skew`	boolean	ConfirmSchemaSkew 는 "rollback 은 스키마를 되돌리지 않음" 을 인지했다는 확인 — 대상 버전 이후 삭제성 변경이 반영된 경우에만 요구됨 (FR-014).

응답 — 202 · 롤백 접수됨 (비동기 적용)

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 412 500 — 에러 처리

`GET /api/v1/apps/{appID}/diagnosis`

deployGetApiV1AppsByAppIDDiagnosis

현재 K8s rollout 상태를 읽어 배포 실패 원인과 신뢰 불가 앱 출력 signal 을 분리해 반환한다.

언어	호출
node	`sdk.deployments.lifecycle.diagnosis(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDDiagnosis(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDDiagnosis(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDDiagnosisAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDDiagnosis(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_diagnosis(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_diagnosis(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDDiagnosis", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

응답 — 200 · 라이브 배포 진단

이름	타입	설명
`appId` (wire: `app_id`)	string
`applicable`	boolean
`healthy`	boolean
`services`	array<object>

에러 status: 400 401 403 404 500 — 에러 처리

`DELETE /api/v1/apps/{appID}/git-connection`

deployDeleteApiV1AppsByAppIDGitConnection

앱의 GitHub 연결을 해제한다. 이후 webhook push 는 매칭되지 않아 자동 배포가 멈춘다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
연결이 없어도 idempotent (200 또는 204).
부수 효과: GitConnection row 삭제. 기존 deployment 이력은 보존.

언어	호출
node	`sdk.apps.git(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployDeleteApiV1AppsByAppIDGitConnection(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployDeleteApiV1AppsByAppIDGitConnection(pathParams, query, body)` — 비동기: `deployDeleteApiV1AppsByAppIDGitConnectionAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployDeleteApiV1AppsByAppIDGitConnection(pathParams, query, body)` — suspend
python	`client.deployments.deploy_delete_api_v1_apps_by_app_id_git_connection(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_delete_api_v1_apps_by_app_id_git_connection(path_params: …, query: …, body: …)`
공통	`request("deployDeleteApiV1AppsByAppIDGitConnection", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

응답 — 204 · 연결 해제됨 (no content)

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 500 — 에러 처리

`GET /api/v1/apps/{appID}/git-connection`

deployGetApiV1AppsByAppIDGitConnection

앱의 GitHub 연결 상태를 discriminated union 으로 반환한다.

호출 권한: 앱이 속한 테넌트의 active 멤버 (cross-tenant 차단). 비-멤버는 404 (앱 존재 비노출).
응답은 connected 를 기준으로 두 가지 모양:
connected: true → provider/repo_full_name/branch/installation_id 포함
connected: false → owner/admin 이면 install_url 포함 (GitHub App 설치 화면, state 토큰 사전 첨부); 그 외 멤버는 install_url 없음
부수 효과: 미연결 + owner/admin 일 때만 install_url 의 state 토큰을 새로 발급 (TTL 10분). 연결됨 또는 비-owner/admin 멤버는 부수 효과 없음.

언어	호출
node	`sdk.apps.git(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDGitConnection(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDGitConnection(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDGitConnectionAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDGitConnection(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_git_connection(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_git_connection(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDGitConnection", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

응답 — 200 · GitHub 연결 상태 (connected discriminator)

이름	타입	설명
`branch`	string	Branch 는 webhook 자동 배포 branch. connected=true 일 때만 채워짐.
`connected`	boolean	Connected 는 discriminator. true 면 아래 connection 필드가, false 면 install_url 이 채워진다.
`installUrl` (wire: `install_url`)	string	InstallURL 은 GitHub App 설치 페이지 URL (state 토큰 사전 첨부). connected=false 일 때만 채워짐. 매 GET 마다 새 state 토큰 발급 (TTL 10분).
`installationId` (wire: `installation_id`)	integer	InstallationID 는 GitHub App installation 식별자. connected=true 일 때만 채워짐.
`provider`	string	Provider 는 git provider 이름 (`github`). connected=true 일 때만 채워짐.
`repoFullName` (wire: `repo_full_name`)	string	RepoFullName 은 `owner/repo`. connected=true 일 때만 채워짐.

에러 status: 400 401 404 500 — 에러 처리

`PATCH /api/v1/apps/{appID}/git-connection`

deployPatchApiV1AppsByAppIDGitConnection

GitHub 연결의 webhook 자동 배포 대상 branch 를 변경한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
branch 이름 형식 위반 시 400 (ErrInvalidBranch).
연결이 없으면 404.
부수 효과: GitConnection.branch 갱신.

언어	호출
node	`sdk.apps.git(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPatchApiV1AppsByAppIDGitConnection(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPatchApiV1AppsByAppIDGitConnection(pathParams, query, body)` — 비동기: `deployPatchApiV1AppsByAppIDGitConnectionAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPatchApiV1AppsByAppIDGitConnection(pathParams, query, body)` — suspend
python	`client.deployments.deploy_patch_api_v1_apps_by_app_id_git_connection(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_patch_api_v1_apps_by_app_id_git_connection(path_params: …, query: …, body: …)`
공통	`request("deployPatchApiV1AppsByAppIDGitConnection", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`branch`	string	Branch 는 새 webhook 자동 배포 branch 이름.

응답 — 200 · 갱신된 GitHub 연결

이름	타입	설명
`branch`	string	Branch 는 webhook 자동 배포 대상 branch.
`installationId` (wire: `installation_id`)	integer	InstallationID 는 GitHub App installation 식별자.
`provider`	string	Provider 는 git provider 이름. 현재는 `github` 만 지원.
`repoFullName` (wire: `repo_full_name`)	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.

에러 status: 400 401 403 404 500 — 에러 처리

`POST /api/v1/apps/{appID}/git-connection`

deployPostApiV1AppsByAppIDGitConnection

GitHub App 설치 callback 후 SPA 가 state + installation_id + repo 를 전달해 앱과 GitHub 저장소를 연결한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
state 는 InstallStart 에서 발급된 1회용 토큰이어야 한다. 만료/중복 사용 시 400. state 가 path 의 다른 앱 것이면 403 (cross-app 혼동대리인 방어).
installation 이 해당 repo 에 접근 권한이 없으면 400 (ErrInstallationVerification).
branch 가 비어있으면 default main. branch 이름 형식 위반 시 400.
부수 효과: GitConnection row 생성 + state 토큰 consume.

언어	호출
node	`sdk.apps.git(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1AppsByAppIDGitConnection(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1AppsByAppIDGitConnection(pathParams, query, body)` — 비동기: `deployPostApiV1AppsByAppIDGitConnectionAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1AppsByAppIDGitConnection(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_apps_by_app_id_git_connection(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_apps_by_app_id_git_connection(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1AppsByAppIDGitConnection", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`branch`	string	Branch 는 webhook 으로 자동 배포할 branch. 비어있으면 `main`.
`installation_id`	integer	InstallationID 는 GitHub App installation 식별자.
`repo_full_name`	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.
`state`	string	State 는 InstallStart 로 발급된 1회용 토큰 (32 byte hex). GitHub App 설치 완료 후 SPA 가 그대로 전달한다.

응답 — 201 · 등록된 GitHub 연결

이름	타입	설명
`branch`	string	Branch 는 webhook 자동 배포 대상 branch.
`installationId` (wire: `installation_id`)	integer	InstallationID 는 GitHub App installation 식별자.
`provider`	string	Provider 는 git provider 이름. 현재는 `github` 만 지원.
`repoFullName` (wire: `repo_full_name`)	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.

에러 status: 400 401 403 404 500 — 에러 처리

`POST /api/v1/apps/{appID}/git/github/connect`

deployPostApiV1AppsByAppIDGitGithubConnect

InstallStart→Register 의 state 토큰 없이 앱과 GitHub 저장소를 연결한다. MCP 에이전트는 브라우저가 없으므로 state 토큰을 받을 수 없고, 대신 백엔드가 보관 중인 사용자 GitHub 토큰으로 installation 소유를 검증한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate) + deploy:write delegation.
검증 순서: ① 호출 사용자가 installation_id 를 소유하는지 (저장된 GitHub user token) ② GitHub App 이 해당 repo 를 읽을 수 있는지 ③ 연결 upsert.
branch 가 비어있으면 default main.
부수 효과: GitConnection row 생성/교체 (idempotent — Register 와 동일).

언어	호출
node	`sdk.apps.git.connectGithub(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1AppsByAppIDGitGithubConnect(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1AppsByAppIDGitGithubConnect(pathParams, query, body)` — 비동기: `deployPostApiV1AppsByAppIDGitGithubConnectAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1AppsByAppIDGitGithubConnect(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_apps_by_app_id_git_github_connect(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_apps_by_app_id_git_github_connect(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1AppsByAppIDGitGithubConnect", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`branch`	string	Branch 는 webhook 으로 자동 배포할 branch. 비어있으면 `main`.
`installation_id`	integer	InstallationID 는 GitHub App installation 식별자. 호출자(에이전트 사용자)가 소유한 installation 이어야 한다 (서버가 user token 으로 검증).
`repo_full_name`	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.

응답 — 201 · 등록된 GitHub 연결

이름	타입	설명
`branch`	string	Branch 는 webhook 자동 배포 대상 branch.
`installationId` (wire: `installation_id`)	integer	InstallationID 는 GitHub App installation 식별자.
`provider`	string	Provider 는 git provider 이름. 현재는 `github` 만 지원.
`repoFullName` (wire: `repo_full_name`)	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.

에러 status: 400 401 403 428 500 — 에러 처리

`GET /api/v1/apps/{appID}/git/github/install/start`

deployGetApiV1AppsByAppIDGitGithubInstallStart · 302 → {status, location}

앱에 연결할 GitHub App 의 설치 화면 URL 로 302 redirect 한다. 일회용 state 토큰을 발급해서 callback 단계의 replay/cross-app 공격을 차단한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
부수 효과: 1회용 state 토큰 row 발급 (TTL 짧음). 사용자는 GitHub 의 install 화면으로 이동.
설치 완료 후 GitHub 가 SPA 로 callback 하면 SPA 가 POST /apps/{appID}/git-connection 을 호출해 연결 완성.

언어	호출
node	`sdk.apps.git(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDGitGithubInstallStart(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDGitGithubInstallStart(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDGitGithubInstallStartAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDGitGithubInstallStart(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_git_github_install_start(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_git_github_install_start(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDGitGithubInstallStart", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

응답 — 2xx

본문 없음 → SDK 는 빈 map {} 반환

302 응답 시 {"status": 302, "location": "..."} 반환 (redirect 미추종)

에러 status: 400 401 403 404 500 — 에러 처리

`GET /api/v1/apps/{appID}/logs`

deployGetApiV1AppsByAppIDLogs

배포된 앱 파드 (K8s) 의 runtime stdout/stderr 를 Cloud Logging 에서 읽어 한 페이지 반환한다. 과거 조회와 실시간 tail 을 같은 엔드포인트로 처리한다.

호출 권한: 앱 owner 또는 테넌트 admin (RequireAppOwnerOrAdmin gate).
direction=backward (기본): 최신부터 과거로 페이징. direction=forward: cursor(watermark) 이후 새 로그만 — ~2초 주기 폴링하면 실시간 tail.
cursor 는 불투명 토큰. 직전 응답의 next_cursor 를 그대로 넘긴다. limit 1~1000 (기본 100). since/until 은 RFC3339.
부수 효과 없음 (read-only). 로그는 저장하지 않고 Cloud Logging 에서 조회만 한다.

언어	호출
node	`sdk.deployments.logs(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDLogs(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDLogs(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDLogsAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDLogs(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_logs(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_logs(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDLogs", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Query 파라미터 — query 로 전달 (문자열 값)

이름	타입	설명
`direction`	string	backward (기본) \| forward
`cursor`	string	이어보기 커서 (직전 응답의 next_cursor)
`since`	string	forward 시작 시각 (RFC3339)
`until`	string	상한 시각 (RFC3339)
`limit`	integer	페이지 크기 (1~1000, 기본 100)

응답 — 200 · 로그 페이지

이름	타입	설명
`hasMore` (wire: `has_more`)	boolean	HasMore 는 더 가져올 페이지가 있는지. forward 에서도 limit 만큼 꽉 차면 true (poll 간격 안 기다리고 바로 이어 받기).
`lines`	array<object>	Lines 는 시간 오름차순 로그 줄. 비어 있으면 해당 구간에 로그 없음.
`nextCursor` (wire: `next_cursor`)	string	NextCursor 를 다음 호출의 cursor 로 그대로 넘기면 이어 받는다 (backward=더 과거, forward=더 새것). 빈 문자열이면 끝.

에러 status: 400 401 403 404 500 503 — 에러 처리

`POST /api/v1/apps/{appID}/promotions/{requestID}/retry`

deployPostApiV1AppsByAppIDPromotionsByRequestIDRetry

실패했거나 promoting 에 갇힌 promote 를 다시 실행한다 (spec 016). 멱등 — 이미 반영된 스키마 변경은 건너뛰고 같은 이미지 재적용은 무해. 접수 즉시 202, 결과는 심사 상세의 promote_status 폴링.

호출 권한: app owner | tenant_admin (RequireAppOwnerOrAdmin gate)
부수 효과: promote_status promoting 전이 + 비동기 promote 재실행

언어	호출
node	`sdk.deployments.lifecycle.retryPromotion(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1AppsByAppIDPromotionsByRequestIDRetry(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1AppsByAppIDPromotionsByRequestIDRetry(pathParams, query, body)` — 비동기: `deployPostApiV1AppsByAppIDPromotionsByRequestIDRetryAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1AppsByAppIDPromotionsByRequestIDRetry(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_apps_by_app_id_promotions_by_request_id_retry(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_apps_by_app_id_promotions_by_request_id_retry(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1AppsByAppIDPromotionsByRequestIDRetry", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID
`requestID` 필수	string	심사 요청 UUID

응답 — 202 · 재시도 접수됨

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 409 412 500 — 에러 처리

`GET /api/v1/apps/{appID}/releases`

deployGetApiV1AppsByAppIDReleases

성공한 배포에 부여된 버전 목록을 최신 버전부터 반환한다 (spec 016 US1).

호출 권한: 인증된 사용자 (RequireAuth).
항목마다 prod/staging 반영 여부(active_*)와 심사 승인 이력(approved)을 포함.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.deployments.lifecycle.releases(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDReleases(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDReleases(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDReleasesAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDReleases(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_releases(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_releases(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDReleases", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Query 파라미터 — query 로 전달 (문자열 값)

이름	타입	설명
`limit`	integer	개수 (기본 20)
`offset`	integer	시작 위치 (기본 0)

응답 — 200 · 버전 목록

이름	타입	설명
`items`	array<object>
`nextCursor` (wire: `next_cursor`)	string
`total`	integer

에러 status: 400 401 404 500 — 에러 처리

`GET /api/v1/apps/{appID}/releases/promote-preflight`

deployGetApiV1AppsByAppIDReleasesPromotePreflight

지정 버전을 promote 할 수 있는지 점검한다 (spec 016 FR-020/FR-007): 이미지 레지스트리 존재 여부, staging↔prod 가 다른 env 키 목록, 이번 promote 에 실릴 스키마 변경 목록(삭제성 표시).

호출 권한: app owner | tenant_admin (Gate.RequireAppOwnerOrAdmin) — 심사 제출(owner)/승인(tenant_admin) 화면이 호출. env 키 이름·스키마 변경 목록이 노출되므로 멤버 전체에 열지 않음.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.deployments.lifecycle.promotePreflight(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1AppsByAppIDReleasesPromotePreflight(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1AppsByAppIDReleasesPromotePreflight(pathParams, query, body)` — 비동기: `deployGetApiV1AppsByAppIDReleasesPromotePreflightAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1AppsByAppIDReleasesPromotePreflight(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_apps_by_app_id_releases_promote_preflight(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_apps_by_app_id_releases_promote_preflight(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1AppsByAppIDReleasesPromotePreflight", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Query 파라미터 — query 로 전달 (문자열 값)

이름	타입	설명
`deployment_id` 필수	string	점검 대상 버전의 배포 UUID

응답 — 200 · 점검 결과

이름	타입	설명
`cursorSeq` (wire: `cursor_seq`)	integer	CursorSeq 는 지금 제출하면 고정될 op 커서.
`diffKeys` (wire: `diff_keys`)	array<string>	DiffKeys 는 staging 값이 prod 와 다른 env 키 — 검증되지 않은 차이 경고 (FR-020).
`missingImages` (wire: `missing_images`)	array<string>	MissingImages 는 레지스트리에서 사라진 이미지 — 있으면 promote 불가.
`ops`	array<object>	Ops 는 이번 promote 에 실릴 스키마 변경 목록 (destructive 구분 포함).
`promotable`	boolean	Promotable 은 즉시 promote 가능 여부 (missing_images 비어있음).

에러 status: 400 401 403 404 412 500 — 에러 처리

`DELETE /api/v1/apps/{appID}/staging`

deployDeleteApiV1AppsByAppIDStaging

앱의 스테이징 환경을 끈다 (spec 016). staging K8s 세트·스키마·미 promote 변경 기록이 함께 폐기된다 — body 의 confirm_discard_ops=true 로 명시적 확인 필수.

호출 권한: app owner | tenant_admin (Gate.RequireAppOwnerOrAdmin)
pending 심사가 있으면 412 — 먼저 취소/처리
부수 효과: staging 파드/호스트 제거, staging 스키마 DROP (데이터 손실)

언어	호출
node	`sdk.deployments.disableStaging(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployDeleteApiV1AppsByAppIDStaging(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployDeleteApiV1AppsByAppIDStaging(pathParams, query, body)` — 비동기: `deployDeleteApiV1AppsByAppIDStagingAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployDeleteApiV1AppsByAppIDStaging(pathParams, query, body)` — suspend
python	`client.deployments.deploy_delete_api_v1_apps_by_app_id_staging(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_delete_api_v1_apps_by_app_id_staging(path_params: …, query: …, body: …)`
공통	`request("deployDeleteApiV1AppsByAppIDStaging", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`confirm_discard_ops`	boolean	ConfirmDiscardOps 는 미 promote 스키마 변경(op 기록)이 함께 폐기됨을 확인했다는 명시적 동의. false/누락 시 412.

응답 — 204 · 스테이징 꺼짐

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 412 500 — 에러 처리

`PUT /api/v1/apps/{appID}/staging`

deployPutApiV1AppsByAppIDStaging

앱의 스테이징 환경을 켠다 (spec 016). 노코드 DB 스키마를 구조 복제(fork)하고 옵트인 플래그를 저장한다. 이후 push 는 staging 에만 반영되고 prod 는 promote 로만 변경.

호출 권한: app owner | tenant_admin (Gate.RequireAppOwnerOrAdmin)
사전 조건: 프로덕션 배포 이력 1회 이상 (promote 가 prod 파드 이미지 patch 라 대상 필요 — 없으면 412)
어느 단계든 실패 시 전체 실패 (반쪽 staging 금지, 생성분 보상 정리)
부수 효과: staging PG 스키마 생성 + 현재 prod 버전을 staging 에 비동기 seed(재빌드 없음, spec 017). seed 완료 전엔 staging URL 이 잠깐 미가용

언어	호출
node	`sdk.deployments.enableStaging(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPutApiV1AppsByAppIDStaging(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPutApiV1AppsByAppIDStaging(pathParams, query, body)` — 비동기: `deployPutApiV1AppsByAppIDStagingAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPutApiV1AppsByAppIDStaging(pathParams, query, body)` — suspend
python	`client.deployments.deploy_put_api_v1_apps_by_app_id_staging(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_put_api_v1_apps_by_app_id_staging(path_params: …, query: …, body: …)`
공통	`request("deployPutApiV1AppsByAppIDStaging", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`appID` 필수	string	앱 UUID

응답 — 202 · 옵트인 접수 — staging seed 는 비동기 진행

본문 없음 → SDK 는 빈 map {} 반환

에러 status: 400 401 403 404 409 412 500 — 에러 처리

`POST /api/v1/git/github/complete`

deployPostApiV1GitGithubComplete

GitHub install callback 이 identity 에서 SPA 로 divert 된 뒤, SPA 가 state + installation_id + repo 를 전달해 앱과 GitHub 저장소를 연결한다. 앱은 path 가 아니라 state 바인딩(st.AppID)에서 복원하므로 leaked state 가 다른 앱으로 redirect 될 수 없다.

호출 권한: 인증된 사용자 (RequireAuth). 인가는 state 소유 검증 — 세션 사용자가 state 의 RequestedBy 와 같아야 한다 (account-takeover 방어).
검증 순서 (verify-before-consume): ① state peek ② 소유(session==RequestedBy) + 만료 ③ installation 소유 ④ GitHub App 이 repo 읽기 가능 ⑤ state 소비 ⑥ 연결 upsert. 성공 확정 전까지 1회용 토큰을 소비하지 않는다.
branch 가 비어있으면 default main. installation_id 누락/0 이하 또는 repo_full_name 누락 시 400.
부수 효과: GitConnection row 생성/교체 + state 토큰 consume.

언어	호출
node	미제공
go	`client.Deployments().DeployPostApiV1GitGithubComplete(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1GitGithubComplete(pathParams, query, body)` — 비동기: `deployPostApiV1GitGithubCompleteAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1GitGithubComplete(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_git_github_complete(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_git_github_complete(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1GitGithubComplete", pathParams, query, body)`

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`branch`	string	Branch 는 webhook 으로 자동 배포할 branch. 비어있으면 `main`.
`installation_id`	integer	InstallationID 는 GitHub App installation 식별자. 호출자(세션 사용자)가 소유한 installation 이어야 한다 (서버가 user token 으로 검증).
`repo_full_name`	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.
`state`	string	State 는 InstallStart 로 발급된 dot 없는 1회용 토큰. GitHub install callback 이 identity 에서 SPA 로 divert 될 때 query 로 전달된 값을 그대로 보낸다.

응답 — 201 · 등록된 GitHub 연결 (app_id + tenant_slug 포함)

이름	타입	설명
`appId` (wire: `app_id`)	string	AppID 는 state 바인딩(st.AppID)에서 복원된 앱 UUID — 연결이 어느 앱에 붙었는지.
`branch`	string	Branch 는 webhook 자동 배포 대상 branch.
`installationId` (wire: `installation_id`)	integer	InstallationID 는 GitHub App installation 식별자.
`provider`	string	Provider 는 git provider 이름. 현재는 `github` 만 지원.
`repoFullName` (wire: `repo_full_name`)	string	RepoFullName 은 `owner/repo` 형식의 GitHub 저장소 이름.
`tenantSlug` (wire: `tenant_slug`)	string	TenantSlug 는 앱이 속한 테넌트 slug. apex→subdomain 이동용. slug 조회 실패 시 빈 값.

에러 status: 400 401 403 428 500 — 에러 처리

`GET /api/v1/github/accounts`

deployGetApiV1GithubAccounts

사용자의 GitHub user 본인 (/user) + 활성 organization 멤버십 (/user/memberships/orgs, state=active) + 이미 axhub App 이 설치된 곳 (/user/installations) 셋을 GitHub API 에서 가져와 합쳐서 한 응답으로 반환. SPA 의 installation picker dim list 용.

호출 권한: 인증된 사용자 (RequireAuth)
부수 효과: token stale 시 PR 3 의 ensureFreshToken 이 refresh + UPSERT (자동)
실패: github_user_tokens row 없음 또는 refresh invalid_grant → 428 github_relogin_required (SPA 가 /auth/github 재시작 유도)

언어	호출
node	`sdk.deployments.github(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1GithubAccounts(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1GithubAccounts(pathParams, query, body)` — 비동기: `deployGetApiV1GithubAccountsAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1GithubAccounts(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_github_accounts(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_github_accounts(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1GithubAccounts", pathParams, query, body)`

응답 — 200 · user + orgs dim list (User 본인 먼저, 그 다음 orgs)

이름	타입	설명
`accounts`	array<object>

에러 status: 401 428 502 — 에러 처리

`GET /api/v1/github/installations/{installationID}/repositories`

deployGetApiV1GithubInstallationsByInstallationIDRepositories

installationID 의 repo 목록 페이지를 반환. 권한 검증: 호출자의 /user/installations 에 installationID 가 포함된 경우만 (다른 사용자 installation 의 repo 노출 방지).

호출 권한: 인증된 사용자 + installation 소유 검증 (handler 안)
페이지네이션: page (1-based, 기본 1), per_page (기본 30, max 100)

언어	호출
node	`sdk.deployments.github(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1GithubInstallationsByInstallationIDRepositories(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1GithubInstallationsByInstallationIDRepositories(pathParams, query, body)` — 비동기: `deployGetApiV1GithubInstallationsByInstallationIDRepositoriesAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1GithubInstallationsByInstallationIDRepositories(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_github_installations_by_installation_id_repositories(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_github_installations_by_installation_id_repositories(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1GithubInstallationsByInstallationIDRepositories", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`installationID` 필수	integer	GitHub installation_id

Query 파라미터 — query 로 전달 (문자열 값)

이름	타입	설명
`page`	integer	1-based page (default 1)
`per_page`	integer	page size, max 100 (default 30)

응답 — 200 · repos 페이지

이름	타입	설명
`repositories`	array<object>	Repositories 는 현재 페이지의 repo 목록.
`totalCount` (wire: `total_count`)	integer	TotalCount 는 페이지네이션 전 전체 repo 수.

에러 status: 400 401 403 428 502 — 에러 처리

`POST /api/v1/tenants/{tenantID}/app-bootstraps`

deployPostApiV1TenantsByTenantIDAppBootstraps

템플릿 + 앱 메타로 GitHub repo 생성 + 템플릿 push + 자동 배포까지의 saga 를 비동기로 시작한다.

호출 권한: path 테넌트의 활성 멤버 (RequireTenantMemberOnPath). tenant 는 URL path 에서 받음 — access JWT 는 tenant-less 라 path 가 단일 진실원.
입력: createBootstrapRequest. template_id 는 GET /api/v1/templates 에서 고른 UUID.
부수 효과: app_bootstraps row 생성 + goroutine saga 시작 (app→repo→push→connect→deploy). GitHub repo 생성 + push 발생.
GitHub App 미설치 (installation_id 누락) 시 422.

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployPostApiV1TenantsByTenantIDAppBootstraps(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployPostApiV1TenantsByTenantIDAppBootstraps(pathParams, query, body)` — 비동기: `deployPostApiV1TenantsByTenantIDAppBootstrapsAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployPostApiV1TenantsByTenantIDAppBootstraps(pathParams, query, body)` — suspend
python	`client.deployments.deploy_post_api_v1_tenants_by_tenant_id_app_bootstraps(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_post_api_v1_tenants_by_tenant_id_app_bootstraps(path_params: …, query: …, body: …)`
공통	`request("deployPostApiV1TenantsByTenantIDAppBootstraps", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`tenantID` 필수	string	테넌트 UUID

Request Body — body 로 전달, wire 키(snake_case) 그대로

이름	타입	설명
`github_installation_id`	integer	GitHubInstallationID 는 사용자가 axhub GitHub App 을 설치하고 받은 ID.
`github_owner`	string	GitHubOwner 는 repo 를 만들 GitHub user 또는 org 이름.
`name`	string	Name 은 앱 표시 이름. 1~100자.
`repo_name`	string	RepoName 은 GitHub 에 만들 repo 이름 (owner 안 unique).
`repo_private`	boolean	RepoPrivate 는 repo 가시성. 기본 private.
`slug`	string	Slug 은 axhub 식별자. 2~64자 [a-z0-9-].
`subdomain`	string	Subdomain 은 접속 주소 라벨. 2~32자. {subdomain}.{tenant}.axhub.ai.
`template_id`	string	TemplateID 는 카탈로그(GET /api/v1/templates)에서 고른 템플릿 UUID.

응답 — 202 · saga 시작 — bootstrap_id + status_url

이름	타입	설명
`bootstrapId` (wire: `bootstrap_id`)	string	BootstrapID 는 진행 상태 polling 에 쓰는 saga id.
`statusUrl` (wire: `status_url`)	string	StatusURL 은 polling endpoint 경로.

에러 status: 400 401 403 422 500 — 에러 처리

`GET /api/v1/tenants/{tenantID}/app-bootstraps/{bootstrapID}`

deployGetApiV1TenantsByTenantIDAppBootstrapsByBootstrapID

bootstrap_id 로 saga 진행 상태 조회. SPA 가 status=done/failed 까지 polling.

호출 권한: path 테넌트의 활성 멤버 (RequireTenantMemberOnPath).
부수 효과 없음 (read-only). 다른 테넌트의 bootstrap 은 404 (격리).

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1TenantsByTenantIDAppBootstrapsByBootstrapID(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1TenantsByTenantIDAppBootstrapsByBootstrapID(pathParams, query, body)` — 비동기: `deployGetApiV1TenantsByTenantIDAppBootstrapsByBootstrapIDAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1TenantsByTenantIDAppBootstrapsByBootstrapID(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_tenants_by_tenant_id_app_bootstraps_by_bootstrap_id(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_tenants_by_tenant_id_app_bootstraps_by_bootstrap_id(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1TenantsByTenantIDAppBootstrapsByBootstrapID", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`tenantID` 필수	string	테넌트 UUID
`bootstrapID` 필수	string	부트스트랩 UUID

응답 — 200 · 진행 상태

이름	타입	설명
`appId` (wire: `app_id`)	string	AppID 는 app stage 통과 후 생성된 앱 UUID (그 전엔 빈 문자열).
`deploymentId` (wire: `deployment_id`)	string	DeploymentID 는 deploy stage 통과 후 배포 UUID.
`errorCode` (wire: `error_code`)	string	ErrorCode 는 status=failed 시 분기 코드 (repo_exists / app_failed / ...).
`errorMessage` (wire: `error_message`)	string	ErrorMessage 는 status=failed 시 상세.
`id`	string	ID 는 saga id.
`repoFullName` (wire: `repo_full_name`)	string	RepoFullName 은 repo stage 통과 후 'owner/repo'.
`stage`	string	Stage 는 현재 단계: app / repo / push / connect / deploy / done.
`status`	string	Status 는 전체 상태: running / done / failed.

에러 status: 400 401 403 404 500 — 에러 처리

`GET /api/v1/tenants/{tenantID}/deployments`

deployGetApiV1TenantsByTenantIDDeployments

테넌트의 모든 앱에 걸친 최근 배포를 최신순으로 반환한다 (인프라 대시보드 배포 피드).

호출 권한: tenant_member (자기 테넌트 한정, RequireTenantMemberOnPath).
limit 은 1~100 (default 20). 각 항목에 app_id 포함 — 호출자가 앱 메타와 join.
부수 효과 없음 (read-only).

언어	호출
node	`sdk.deployments(…)` — 리소스 모델 — 인자·반환 타입은 패키지의 TypeScript 정의 참조
go	`client.Deployments().DeployGetApiV1TenantsByTenantIDDeployments(ctx, axhub.OperationParams{PathParams: …, Query: …, Body: …})`
java	`client.deployments().deployGetApiV1TenantsByTenantIDDeployments(pathParams, query, body)` — 비동기: `deployGetApiV1TenantsByTenantIDDeploymentsAsync(…)` → CompletableFuture
kotlin	`client.deployments.deployGetApiV1TenantsByTenantIDDeployments(pathParams, query, body)` — suspend
python	`client.deployments.deploy_get_api_v1_tenants_by_tenant_id_deployments(path_params=…, query=…, body=…)` — AsyncAxHubClient 는 동일명 await
ruby	`client.deployments.deploy_get_api_v1_tenants_by_tenant_id_deployments(path_params: …, query: …, body: …)`
공통	`request("deployGetApiV1TenantsByTenantIDDeployments", pathParams, query, body)`

Path 파라미터 — pathParams 로 전달

이름	타입	설명
`tenantID` 필수	string	테넌트 UUID

Query 파라미터 — query 로 전달 (문자열 값)

이름	타입	설명
`limit`	integer	개수 (1~100, 기본 20)

응답 — 200 · 최근 배포 목록

이름	타입	설명
`items`	array<object>
`nextCursor` (wire: `next_cursor`)	string
`total`	integer

에러 status: 400 401 403 500 — 에러 처리