배포 관리
배포 상태를 읽고, push하면 자동으로 배포되게 하고, 배포 전에 점검하고, 로그로 실패 지점을 찾고, 이전 버전으로 되돌리는 방법이에요.
앱을 올린 다음에는 지금 어떤 상태인지 보고, 문제가 생기면 원인을 찾아 되돌릴 수 있어야 해요.
배포 상태 읽는 법부터 자동 배포 붙이기, 로그로 실패 지점 찾기, 이전 버전으로 되돌리기까지 다뤄요.
배포 상태 보는 법
앱 콘솔과 앱 목록에 보이는 배포 상태는 코드가 실제로 떠 있는지를 나타내요. 네 가지 값 중 하나예요.
| 배포 상태 | 뜻 |
|---|---|
| 배포 전 | 아직 성공한 배포가 없어요 — 앱은 만들었지만 코드가 떠 있지 않은 상태예요 |
| 배포됨 | 첫 배포가 성공하면 자동으로 바뀌어요 — 코드가 실제로 떠서 접속할 수 있어요 |
| 일시정지 | 멈추고 주소를 닫은 상태예요 — 다시 시작하면 마지막 성공 배포가 자동으로 다시 떠요 |
| 삭제됨 | 삭제한 앱이에요 — 30일 안에 삭제 취소하지 않으면 영구 삭제돼요 |
배포됨 앱이 절전 중이면 절전 중, 깨어나는 동안은 깨우는 중으로 함께 보여요. 절전은 배포 상태를 바꾸지 않아요 — 들어오면 저절로 깨어나요.
배포에 성공했다고 남에게 보이는 건 아니에요 — 누가 볼 수 있는지는 공개 · 접근 관리에서 따로 정해요.
터미널에서는 axhub로 시작하는 명령어 도구(CLI)로 확인해요.
axhub deploy status --app demo # 최신 배포 상태
axhub deploy list --app demo # 배포 이력 목록
axhub deploy watch <deployment_id> --app demo # 배포가 끝날 때까지 지켜보기
axhub deploy cancel <deployment_id> --app demo --execute # 도는 중인 배포 멈추기배포 한 건 한 건의 진행 상태 코드가 궁금하면 axhub deploy codes가 값 하나하나를 설명해 줘요.
절전 · 일시정지 · 삭제 같은 상태 바꾸기는 앱 상태 관리하기에서 다뤄요.
push하면 자동으로 배포되게
코드를 어디에 두느냐에 따라 달라요. 앱 콘솔 → 저장소 탭에서 어느 쪽인지 볼 수 있어요.
- Axhub 저장소를 쓰는 앱 — 연결할 게 없어요. 앱을 만들 때 저장소와 자동 배포가 함께 준비돼요. 코드를 받고 push하는 법은 Axhub 저장소로 코드 관리하기에 있어요.
- GitHub을 쓰는 앱 — 아래처럼 AxHub GitHub App 연결만 해 두면 workflow를 직접 짤 필요가 없어요.
axhub apps git connect --app <app> --repo owner/repo --branch main --execute
axhub apps git status --app <app>연결한 뒤로는 그 저장소에 새 커밋을 push할 때마다 GitHub이 AxHub에 알려 자동으로 새 배포가 시작돼요. push하고 나서 앱 콘솔의 업데이트·공개 탭에 새 배포가 도는 게 보이면 성공이에요.
배포 전에 테스트를 돌리고 싶으면 axhub.yaml에 적어 두면 돼요 — 빌드 전에 실행되고, 실패하면 배포가 멈춰요.
ci:
commands:
- npm test배포 전에 점검하기
axhub deploy check는 배포를 만들기 전에 배포를 실패하게 만들 문제를 미리 찾아요. 아무것도 바꾸지 않는 읽기 전용 명령이에요. axhub.yaml이 있는 앱 폴더에서 실행해요.
axhub deploy check --app demo--app을 빼면 내 컴퓨터에서 볼 수 있는 것만 보고, 앱이 있어야 볼 수 있는 항목은 참고로 넘어가요.
무엇을 보나요
항목 (code) | 무엇을 보나 | 막히면 할 일 |
|---|---|---|
required_env_missing | axhub.yaml의 env.required에 적은 값 중 앱에 아직 등록하지 않은 것. PORT · DATABASE_URL 처럼 AxHub가 넣어 주는 값은 빼고 봐요. 내 .env · .env.local에 있는 이름이면 함께 알려 줘요 | 값을 등록해요 — 환경변수 설정하기. .env에 있으면 axhub env set --app demo --from-dotenv .env --execute로 한 번에 올릴 수 있어요 |
commit_not_on_remote | 지금 커밋이 GitHub 저장소에 올라가 있는지. GitHub 앱만 봐요 | 안내된 git push origin <브랜치>를 실행해요 |
uncommitted_changes | 아직 커밋하지 않은 변경이 있는지. .env 파일은 빼고 봐요 | 커밋하고 push해요. .env는 커밋하지 말고 환경변수로 등록해요 |
subdomain_not_configured | 서버 앱(docker · compose)에 접속 주소가 정해져 있는지 | 주소를 정해요 — 접속 주소 |
challenge_deploy_locked | 대회 배포 마감 중인 팀 앱인지 | 운영진이 배포를 다시 열 때까지 기다려요 |
결과 읽는 법
줄마다 앞에 판정이 붙어요. --json이면 status 값으로 나와요.
| 화면 | status | 뜻 |
|---|---|---|
| 통과 | pass | 문제없어요 |
| 막힘 | fail | 이대로 배포하면 실패해요. 하나라도 있으면 마지막에 「배포 전에 맞출 것이 있어요.」가 나오고 종료 코드 9로 끝나요 |
| 확인 못 함 | unknown | 권한 · 네트워크 같은 이유로 판정하지 못했어요. 배포는 막지 않아요 |
| 참고 | info | 앱을 지정하지 않았거나 첫 배포라 확인하지 않았어요. 배포는 막지 않아요 |
axhub.yaml 자체가 잘못됐으면 종료 코드 64로 끝나요.
AI 에이전트가 쓰기 좋게 --json 결과의 항목마다 handling이 붙어요.
handling | 뜻 |
|---|---|
auto | 사용자에게 묻지 않고 해결할 수 있어요 — 커밋 · push, .env에 이미 있는 값 등록 |
ask | 사용자만 아는 값이 필요해요 — .env에 없는 설정값, 접속 주소 |
stop | 사용자도 에이전트도 풀 수 없어요. 아무것도 바꾸지 말고 이유를 알리고 멈춰요 — 대회 배포 마감 |
prevents에는 그 항목이 미리 막아 주는 배포 실패 코드(prepare.required_env_missing · resolve.commit_not_found 등)가 들어 있어요. 실패 코드별 원인은 AXHub에 맞게 앱 만들기에 있어요.
로그 읽는 법
배포가 실패로 떴다면 로그부터 열어요. 앱 콘솔의 업데이트·공개 탭에서 실패한 배포를 누르면 로그가 보이고, 터미널에서는 이렇게 봐요.
axhub deploy logs --app demo # 최근 로그
axhub deploy logs --app demo --follow # 실시간으로 이어 보기
axhub deploy logs --app demo --since 2026-08-08T09:00:00Z --limit 200로그에서 볼 것은 하나예요 — 어느 단계에서 멈췄는지. 코드를 실행 형태로 조립하는 빌드 단계에서 멈췄으면 빌드 명령 · 의존성 문제이고, 빌드는 끝났는데 뜨자마자 죽었으면 실행 명령 · 포트 · 환경변수 쪽이고, 빌드는 끝났는데 60초 안에 뜨지 못했으면 헬스체크 대기 시간 쪽이에요 (헬스체크 대기 시간). 마지막 빨간 줄 근처를 그대로 복사해 두세요 — 증상별 해결은 배포가 안 될 때, 실패 사유 코드별 조치는 헬스체크 실패 사유 코드에 있어요.
로그만으로 부족하면 진단 명령이 있어요.
axhub deploy doctor --app demo # 앱의 배포 환경 진단
axhub deploy diagnose demo # 지금 떠 있는 앱의 라이브 상태 진단이전 버전으로 되돌리기 (롤백)
새 버전에 문제가 있으면 이전 성공 버전으로 되돌려요 — 이걸 롤백이라고 해요. 앱 콘솔의 업데이트·공개 탭 → 업데이트 기록에서 이 버전으로 되돌리기를 눌러도 되고, 터미널에서는 이렇게 해요.
돌아갈 지점 찾기
axhub deploy releases --app demo로 릴리즈 이력을 보고, 돌아가고 싶은 배포의 ID를 확인해요.미리보기로 확인
axhub deploy rollback --app demo --from-deployment <deployment_id> — 기본이 미리보기라서 아직 아무것도 바뀌지 않아요.실행
--execute를 붙이면 그 버전이 다시 떠요. 끝난 뒤 axhub deploy verify <deployment_id> --app demo로 성공을 확인해요.롤백은 코드만 되돌려요. 이미 적용된 데이터베이스 스키마 변경(컬럼 삭제 같은 파괴적 변경)은 되돌아가지 않아요 — 이 경우 CLI가 --confirm-schema-skew로 확인을 요구해요. 스키마를 바꾼 배포를 되돌릴 때는 데이터 쪽 영향을 먼저 확인하세요.
앱 주소에 접속해서 이전 버전 화면이 보이면 성공이에요. 원인을 고친 뒤 다시 배포하면 다시 최신 버전으로 올라가요.