🐞 CI/CD 오류: GHCR을 이용한 GitHub Actions 최적화 배포

1. 문제 상황

기존에 사용하던 GitHub Actions 구성은 다음과 같았다. 

name: Deploy to Raspberry Pi 

on:
  push:
    branches: [ main ]

jobs:
  deploy:
    name: Deploy via SSH
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout repository
        uses: actions/checkout@v4
        with:
          fetch-depth: 0
          
      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.7.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
          
      - name: SSH and deploy to Raspberry Pi
        run: |
          ssh -p ${{ secrets.RASPBERRY_PORT }} -o StrictHostKeyChecking=no ${{ secrets.RASPBERRY_USER }}@${{ secrets.RASPBERRY_HOST }} << 'EOF'
            set -euo pipefail
            
            cd /home/${{ secrets.RASPBERRY_USER }}/docker-compose/bluecool/blue
            git fetch --all --prune
            git reset --hard origin/main
            git config core.ignorecase false
            
            docker compose build --no-cache blue
            docker compose up -d --force-recreate blue
            
            docker image prune -f || true
          EOF

프로젝트 규모가 작을때에는 문제가 없었지만 점점 규모가 커지면서 서버 측에서 docker compose build --no-cache 를 수행하는 방식 때문에 빌드 시간이 증가하여 타임아웃이 발생했다. 

2. 해결 방법

CI에서 이미지를 GHCR에 빌드/푸시하고 서버는 빌드 없이 pull만 하도록 변경했다.

GHCR은 GitHub에서 제공하는 컨테이너 이미지 저장소 서비스이다. Docker Hub와 유사한 역할을 수행하며 별도의 외부 레지스트리 설정 없이 GitHub Actions 내에서 이미지 푸시 및 관리가 가능하다.

변경된 설정은 아래와 같다. 

name: Build & Deploy to Raspberry Pi

on:
  push:
    branches: [ main ]
    
concurrency:
  group: blue-deploy-${{ github.ref }}
  cancel-in-progress: true
  
env:
  IMAGE_NAME: ghcr.io/bluecool12/blue
    
jobs:
  build:
    name: Build & Push (GHCR)
    runs-on: ubuntu-latest
    permissions:
      contents: read
      packages: write
    steps:
      - uses: actions/checkout@v4
      
      - uses: docker/setup-qemu-action@v3
      - uses: docker/setup-buildx-action@v3
      
      - uses: docker/login-action@v3
        with:
          registry: ghcr.io
          username: ${{ github.actor }}
          password: ${{ secrets.GITHUB_TOKEN }}
           
      - name: Build & Push
        uses: docker/build-push-action@v5
        with:
          context: .
          platforms: linux/arm64
          push: true
          tags: |
            ${{ env.IMAGE_NAME }}:latest
            ${{ env.IMAGE_NAME }}:${{ github.sha }}
          cache-from: type-gha
          cache-to: type-gha,mode=max
          build-args: |
            NEXT_PUBLIC_API_BASE_URL=${{ vars.NEXT_PUBLIC_API_BASE_URL }}
            PUBLIC_API_BASE_URL=${{ vars.PUBLIC_API_BASE_URL }}
            
  deploy:
    name: Deploy via SSH (pull & up)
    runs-on: ubuntu-latest
    needs: build
    steps:
      - name: Setup SSH
        uses: webfactory/ssh-agent@v0.7.0
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }} 
          
      - name: Add host key (known_hosts)
        run: |
          mkdir -p ~/.ssh
          ssh-keyscan -p "${{ secrets.RASPBERRY_PORT }}" -H "${{ secrets.RASPBERRY_HOST }}" >> ~/.ssh/known_hosts
          chmod 700 ~/.ssh
          chmod 644 ~/.ssh/known_hosts
          
      - name: SSH and deploy to Raspberry Pi
        run: |
          ssh -p ${{ secrets.RASPBERRY_PORT }} \
              -o ServerAliveInterval=30 -o ServerAliveCountMax=10 \
              ${{ secrets.RASPBERRY_USER }}@${{ secrets.RASPBERRY_HOST }} << 'EOF'
            set -Eeuo pipefail
            
            cd /home/${{ secrets.RASPBERRY_USER }}/docker-compose/bluecool/blue
            
            git fetch --all --prune || true
            git reset --hard origin/main || true
            git config core.ignorecase false || true
            
            docker compose pull blue
            docker compose up -d blue
            docker image prune -f || true
          EOF

기존의 Dockerfile을 레포지토리로 옮기고 GitHub Actions에서 GHCR로 이미지를 빌드/푸시하도록 구성하였고 Buildx를 도입하였다.

Buildx는 Docker의 차세대 빌드 엔진인 BuildKit을 기반으로 하는 확장 도구다. 멀티 플랫폼 빌드를 지원하며 GitHub Actions 전용 캐시(type-gha)를 활용해 빌드 시간을 획기적으로 단축할 수 있다.

홈서버에서는 docker-compose.yml이 해당 이미지를 참조하도록 수정하고 환경변수 또한 GitHub Variables를 통해 주입하였다. 

또한 SSH 접속 시 호스트 인증을 생략하지 않고 known_hosts에 키를 미리 등록하는 방식으로 보안을 강화하였다.