문서 본문으로 건너뛰기
솜사탕 Docs배포
가이드베타업데이트 2026-07-24기능 검증 2026-07-24

GitHub 배포

GitHub App으로 저장소를 연결하고 수동 배포와 push 자동 배포를 사용합니다.

이 문서에서 다루는 내용

저장소 연결

  • GitHub App 설치 화면에서 솜사탕이 접근할 저장소를 선택합니다.
  • private 저장소가 목록에 없으면 GitHub App 설치 범위와 현재 로그인한 GitHub 계정을 확인합니다.
  • 저장소를 선택하면 GitHub에서 실제 브랜치 목록을 조회하며 기본 브랜치와 보호 브랜치를 함께 표시합니다.
  • 빈 서비스는 배포 탭의 소스 연결하기 또는 설정의 소스 영역에서 저장소와 브랜치를 처음 연결합니다.
  • 다른 GitHub 계정으로 바꾸려면 기존 연결을 해제한 뒤 원하는 계정으로 다시 연결합니다.

배포 브랜치 선택

서비스 생성과 서비스 설정에서 목록에 있는 브랜치만 선택할 수 있습니다. 설정에서 브랜치를 바꾸면 이후 수동 배포와 Auto Deploy가 사용할 소스가 바뀌며, 저장만으로 배포가 시작되지는 않습니다.

  • 현재 설정된 브랜치가 삭제됐거나 GitHub App에서 확인되지 않으면 기존 이름을 유지한 채 다시 선택하라는 안내가 표시됩니다.
  • 목록이 비었으면 GitHub에서 첫 commit과 브랜치를 만든 뒤 다시 확인합니다.
  • 권한 또는 인증 오류가 나면 다시 확인, GitHub 다시 연결 또는 GitHub App 설정 열기 안내를 따릅니다.
  • 브랜치가 1,000개를 넘으면 일부만 표시되므로 필요한 브랜치가 보이지 않을 때 저장소의 브랜치를 정리한 뒤 다시 확인합니다.

수동 배포

  1. 1
    브랜치와 앱 경로를 확인합니다
    선택한 실제 브랜치와, 모노레포라면 Root Directory가 앱 폴더를 가리키는지 확인합니다.
  2. 2
    배포를 시작합니다
    같은 서비스에서 이미 배포가 진행 중이면 완료될 때까지 기다립니다.
  3. 3
    로그와 상태를 확인합니다
    빌드가 끝나면 앱 실행과 공개 URL 확인이 이어집니다. 실패 단계에 표시된 안내부터 해결하세요.

push 자동 배포

Auto Deploy를 켜면 연결된 저장소와 브랜치에 push가 들어올 때 새 배포를 시작합니다. 이미 같은 서비스의 배포가 진행 중이면 가장 최신 커밋 한 건이 다음 배포로 대기합니다. 기다리는 동안 push가 더 들어오면 대기 중인 배포가 최신 커밋으로 갱신되고, 선행 배포가 성공하거나 실패한 뒤 자동으로 시작됩니다. 중간 push마다 별도 빌드를 만들지는 않으며 다른 브랜치 push는 해당 서비스에 영향을 주지 않습니다.

다음 배포 대기 확인
프로젝트에는 현재 진행 중인 배포와 다음 배포 대기가 함께 표시될 수 있습니다. 대기 중 추가 push가 반영되면 최신 push N회 반영으로 확인할 수 있습니다. 선행 배포가 끝난 뒤에도 시작되지 않거나 실패하면 GitHub 접근 권한, 앱 사전 검증, 환경변수와 플랜 사용 한도 안내를 확인하세요.