/엔지니어/Git / CI·CD/GitHub Actions로 Docker 이미지 빌
Git / CI·CD중급Ubuntugithub-actionsdockerci-cd

GitHub Actions로 Docker 이미지 빌드 및 레지스트리 배포 자동화

GitHub Actions 워크플로우로 Docker 이미지를 빌드하고 GHCR 또는 Docker Hub에 푸시하는 CI/CD 파이프라인을 구성합니다.

전체 흐름

CODE
git push → GitHub Actions 트리거
→ 코드 체크아웃
→ Docker 이미지 빌드
→ 레지스트리 푸시 (GHCR / Docker Hub)
→ 서버에서 docker pull + 재시작

GHCR(GitHub Container Registry) 배포

YAML
# .github/workflows/docker-build.yml

name: Docker Build & Push

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

env:
  REGISTRY: ghcr.io
  IMAGE_NAME: ${{ github.repository }}

jobs:
  build-and-push:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write

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

      - name: Log in to GHCR
        uses: docker/login-action@v3
        with:
          registry: ${{ env.REGISTRY }}
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@v5
        with:
          images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=sha,prefix=sha-
            type=semver,pattern={{version}}

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@v3

      - name: Build and push
        uses: docker/build-push-action@v5
        with:
          context: .
          push: ${{ github.event_name != 'pull_request' }}
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}
          cache-from: type=gha
          cache-to: type=gha,mode=max

빌드 후 서버 자동 배포

YAML
      - name: Deploy to server
        if: github.ref == 'refs/heads/main'
        uses: appleboy/ssh-action@v1
        with:
          host: ${{ secrets.SERVER_HOST }}
          username: ${{ secrets.SERVER_USER }}
          key: ${{ secrets.SSH_PRIVATE_KEY }}
          script: |
            docker pull ghcr.io/${{ github.repository }}:main
            docker compose -f /opt/app/docker-compose.yml up -d app
            docker image prune -f

Secrets 설정

GitHub 저장소 → Settings → Secrets and variables → Actions:

Secret 이름
SERVER_HOST서버 IP 또는 도메인
SERVER_USERSSH 사용자명
SSH_PRIVATE_KEYSSH 개인키 (-----BEGIN OPENSSH PRIVATE KEY----- ...)

GITHUB_TOKEN은 Actions가 자동으로 제공합니다.


멀티 아키텍처 빌드 (ARM 지원)

YAML
      - name: Set up QEMU
        uses: docker/setup-qemu-action@v3

      - name: Build and push (multi-arch)
        uses: docker/build-push-action@v5
        with:
          platforms: linux/amd64,linux/arm64
          push: true
          tags: ${{ steps.meta.outputs.tags }}

ARM 서버(AWS Graviton, Raspberry Pi)와 x86 서버를 동시에 지원할 때 사용합니다.


캐시로 빌드 속도 개선

cache-from: type=gha / cache-to: type=gha,mode=max 설정만으로 GitHub Actions 캐시를 활용합니다. 레이어 변경이 없으면 재빌드하지 않아 빌드 시간이 크게 단축됩니다.

#github-actions#docker#ci-cd#ghcr#자동배포
편집 안내 · Editorial Note

이 가이드는 AI 도구를 활용해 초안을 구성하고 사람이 명령어·문맥을 검토해 발행했습니다. 운영체제와 도구 버전에 따라 결과가 달라질 수 있으므로 적용 전 공식 문서를 함께 확인하세요. 오류를 발견하시면 이메일로 제보해 주세요.

질문 & 답변 (Q&A)

이 가이드에 대해 궁금한 점을 질문해보세요. 확인 후 답변드립니다.