전체 흐름
git push → GitHub Actions 트리거
→ 코드 체크아웃
→ Docker 이미지 빌드
→ 레지스트리 푸시 (GHCR / Docker Hub)
→ 서버에서 docker pull + 재시작GHCR(GitHub Container Registry) 배포
# .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빌드 후 서버 자동 배포
- 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 -fSecrets 설정
GitHub 저장소 → Settings → Secrets and variables → Actions:
| Secret 이름 | 값 |
|---|---|
SERVER_HOST | 서버 IP 또는 도메인 |
SERVER_USER | SSH 사용자명 |
SSH_PRIVATE_KEY | SSH 개인키 (-----BEGIN OPENSSH PRIVATE KEY----- ...) |
GITHUB_TOKEN은 Actions가 자동으로 제공합니다.
멀티 아키텍처 빌드 (ARM 지원)
- 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 캐시를 활용합니다. 레이어 변경이 없으면 재빌드하지 않아 빌드 시간이 크게 단축됩니다.
이 가이드는 AI 도구를 활용해 초안을 구성하고 사람이 명령어·문맥을 검토해 발행했습니다. 운영체제와 도구 버전에 따라 결과가 달라질 수 있으므로 적용 전 공식 문서를 함께 확인하세요. 오류를 발견하시면 이메일로 제보해 주세요.
질문 & 답변 (Q&A)
이 가이드에 대해 궁금한 점을 질문해보세요. 확인 후 답변드립니다.