GHCR로 백엔드 도커 이미지 자동 빌드 & 푸시

이 글에서는 GHCR(GitHub Container Registry) 에 백엔드 이미지를 자동으로 빌드&푸시하고

프론트에서 docker-compose로 이미지를 끌어와 헬스 체크까지 확인하는 전체 흐름을 정리하려 합니다.

바로 복붙해 활용할 수 있도록 터미널 명령어와 GitHub Actions 워크플로 파일을 모두 제공하겠습니다.

 

---

 

GHCR란?

GitHub이 제공하는 컨테이너 이미지 레지스트리입니다.

레포/팀 권한과 자연스럽게 연동되고 GitHub Actions의 GITHUB_TOKEN으로 인증해 추가 시크릿 없이 CI에서 푸시할 수 있습니다.

Public 패키지로 설정하면 누구나 로그인 없이 pull 할 수 있으며 기본 공개 범위는 Private로 생성됩니다.

 

---

 

수동: 로컬에서 GHCR로 푸시

우선 프로젝트 루트에 Dockerfile이 있다고 가정합니다.

Developer Settings에서 토큰 PAT을 생성할 때 packages: write, packages: read를 체크해야 합니다.

# 1. 이미지 빌드하기
docker build -t perfaudit-api:0.1.0 .

# 2. GHCR 로그인 (개인 액세스 토큰 PAT 필요)
#    USERNAME 자리에 GitHub 사용자명 넣기
#    CR_PAT 환경변수에 엑세스 토큰 PAT를 담아 파이프로 전달하기
echo "$CR_PAT" | docker login ghcr.io -u USERNAME --password-stdin

# 3. 태깅하기
docker tag perfaudit-api:0.1.0 ghcr.io/USERNAME/perfaudit-api:0.1.0

# 4. 푸시하기
docker push ghcr.io/eonseojiancasino/perfaudit-api:0.1.0

 

패키지 공개 여부 전환은 패키지 상세 화면의 설정에서 할 수 있으며

Container registry의 Public 패키지는 익명 pull 이 가능해 프론트 동료가 로그인 없이 사용할 수 있습니다.

 

---

 

자동화: GitHub Actions로 자동 빌드/푸시

레포에 다음 파일을 생성합니다 .github/workflows/publish-image.yml

name: publish-image

on:
  push:
    branches: ["develop", "main"]   # develop에 머지, main은 latest
    tags: ["v*"]                    # v1.2.3 같은 릴리스 태그도 발행한다

permissions:
  contents: read
  packages: write                   # GHCR 푸시 권한

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    concurrency:
      group: publish-image-${{ github.ref_name }}
      cancel-in-progress: true

    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Login to GHCR
        uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.repository_owner }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Docker meta (tags & labels)
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ghcr.io/${{ github.repository_owner }}/perfaudit-api
          tags: |
            # 브랜치 태그
            type=ref,event=branch
            # 릴리스 태그 (v*)
            type=ref,event=tag
            # 짧은 SHA 태그
            type=sha,format=short
            # 편의 태그
            type=raw,value=develop,enable=${{ github.ref_name == 'develop' }}
            type=raw,value=latest,enable=${{ github.ref_name == 'main' }}

      - name: Build & Push
        uses: docker/build-push-action@v6
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

 

 

• docker/login-action 으로 GHCR에 로그인합니다. (GitHub가 자동 주입하는 GITHUB_TOKEN을 사용함) 
• docker/metadata-action 으로 이벤트(브랜치/태그/SHA)에 따라 태그와 라벨을 자동 생성합니다. 
• docker/build-push-action 으로 Buildx/BuildKit 기반 빌드 및 푸시를 수행합니다. 캐시를 gha로 설정하면 반복 빌드가 빨라집니다.

 

github.repository_owner와 secrets.GITHUB_TOKEN은 따로 시크릿을 추가하지 않아도 Actions가 자동 제공합니다.
푸시 권한은 permissions: packages: write로 부여합니다.

 

---

 

프론트에서 이미지 소비

프론트 레포에 docker-compose.backend.yml 파일을 둡니다.

services:
  db:
    image: postgres:16
    environment:
      POSTGRES_PASSWORD: postgres
      POSTGRES_USER: postgres
      POSTGRES_DB: perfaudit
    ports: ["5432:5432"]
    healthcheck:
      test: ["CMD-SHELL","pg_isready -U postgres -d perfaudit"]
      interval: 5s
      timeout: 3s
      retries: 10
    volumes:
      - dbdata:/var/lib/postgresql/data

  api:
    image: ghcr.io/USERNAME/perfaudit-api:develop   # 또는 :latest / :v1.2.3
    environment:
      SPRING_PROFILES_ACTIVE: docker
    depends_on:
      db:
        condition: service_healthy
    ports: ["8080:8080"]

volumes:
  dbdata: {}

 

 

공개  패키지 일 때

docker compose -f docker-compose.backend.yml up -d
curl http://localhost:8080/actuator/health
curl http://localhost:8080/api/ping

 

비공개 패키지 일 때

echo '<PAT>' | docker login ghcr.io -u USERNAME --password-stdin
docker compose -f docker-compose.backend.yml pull api
docker compose -f docker-compose.backend.yml up -d
curl http://localhost:8080/actuator/health
curl http://localhost:8080/api/ping

 

공개 패키지는 익명 pull이 가능하지만, 비공개 패키지는 docker login ghcr.io 후 pull 해야 합니다.

 

---

마무리

이 구성을 적용하면 개발 브랜치에 머지되는 즉시 이미지가 GHCR로 발행되고

프론트는 코드 없이 이미지만으로 백엔드를 올려 연동 테스트를 수행할 수 있습니다.

이렇게 함으로써 팀 온보딩 속도가 크게 빨라질 수 있습니다!