26S23a

GitHub Release나 일반 Git 저장소에 바이너리/압축 파일 형태로 올려둔 것은 docker pull 형태(OCI/Docker Registry 프로토콜)로 바로 다운로드받을 수 없습니다.

docker pull <주소>/<이미지>:<태그> 명령은 단순 HTTP 파일 다운로드가 아니라 OCI Image Registry V2 API 규격(Manifest, Config, Layer Blob 조회)을 만족하는 컨테이너 레지스트리 서버와 통신해야 하기 때문입니다.

이를 해결하고 docker pull 명령어로 다운로드받게 만드는 표준 방법은 다음과 같습니다.

---

방법 1. GitHub Packages (GHCR - ghcr.io) 사용 (가장 추천)

GitHub 자체에서 제공하는 공식 컨테이너 레지스트리인 GitHub Container Registry (ghcr.io)를 이용하는 방식입니다.

GitHub Release에 수동으로 파일을 올리는 대신, GitHub의 패키지 기능을 통해 이미지를 푸시해 두면 도커 레지스트리 주소로 바로 당겨올 수 있습니다.

# 1. GitHub CLI 또는 Personal Access Token(PAT)으로 로그인
echo $GH_PAT | docker login ghcr.io -u <GITHUB_USERNAME> --password-stdin

# 2. 이미지 태그를 ghcr.io 주소 체계로 지정
docker tag my-image:latest ghcr.io/<GITHUB_USERNAME>/my-image:latest

# 3. GitHub 패키지 레지스트리로 푸시
docker push ghcr.io/<GITHUB_USERNAME>/my-image:latest

# 4. 클라이언트에서 docker pull로 다운로드 (저장소 Public 전환 시 인증 불필요)
docker pull ghcr.io/<GITHUB_USERNAME>/my-image:latest

---

방법 2. GitHub Actions로 Release 파일 $\rightarrow$ Docker Hub(docker.io) 자동 푸시

Release에 파일이나 코드가 업로드되는 이벤트를 감지하여, GitHub Actions가 이를 컨테이너 이미지로 빌드/패키징한 뒤 Docker Hub(docker.io)로 자동으로 밀어 넣도록 워크플로우를 구성하는 방식입니다.

.github/workflows/docker-publish.yml 예시:

name: Publish to Docker Hub

on:
  release:
    types: [published]

jobs:
  push_to_registry:
    runs-on: ubuntu-latest
    steps:
      - name: Check out the repo
        uses: actions/checkout@v4

      - name: Log in to Docker Hub
        uses: docker/login-action@v3
        with:
          username: ${{ secrets.DOCKERHUB_USERNAME }}
          password: ${{ secrets.DOCKERHUB_TOKEN }}

      - name: Build and push Docker image
        uses: docker/build-push-action@v5
        with:
          context: .
          push: true
          tags: docker.io/${{ secrets.DOCKERHUB_USERNAME }}/my-image:${{ github.ref_name }}

이렇게 구성해 두면 GitHub에서 Release를 찍는 순간 docker.io/<사용자>/my-image:<태그>로 이미지가 배포되어 바로 pull이 가능해집니다.

---

방법 3. Release에 tar 파일 형태로 올려두고 로컬에서 가져오는 경우

레지스트리를 거치지 않고 오직 GitHub Release 애셋(tar 파일)으로만 배포해야 한다면, 클라이언트는 docker pull 대신 curl 다운로드 후 docker load 파이프라인을 사용해야 합니다.

# GitHub Release의 tar 파일을 다운로드받으며 즉시 Docker 로컬 엔진에 적재
curl -sL https://github.com/<USER>/<REPO>/releases/download/v1.0.0/my-image.tar.gz | docker load

==