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

[문제 요약] 

• 증상: GitHub Actions를 통한 배포 중 Connection timeout 발생
• 원인: 프로젝트 규모 증가로 홈서버에서 직접 Docker 빌드가 오래 걸려 SSH 세션/작업 제한 시간을 초과
• 해결: GitHub Actions에서 GHCR(GitHub Container Registry)로 이미지를 빌드·푸시, 서버는 이미지 pull 후 재배포 

기존에 사용하던 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 StrictHostKeyCheking=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 를 수행하는 방식 때문에 빌드 시간이 증가하여 타임아웃이 발생했다. 

따라서 CI에서 이미지를 GHCR에 빌드·푸시하고 서버는 빌드 없이 pull만 하도록 변경했다. 변경된 설정은 아래와 같다. 
 

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
            doccker image prune -f || true
          EOF

기존의 Dockerfile을 레포지토리로 옮기고 GitHub Actions에서 GHCR로 이미지를 빌드·푸시하도록 구성하였고 Buildx 캐시를 활용해 빌드 속도까지 최적화 하였다. 

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

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