GitHub Actions로 CI/CD 파이프라인 구축하기

Alpacon GitHub Actions를 이용한 단계별 CI/CD 파이프라인 구축 튜토리얼입니다.

학습 목표

이 튜토리얼을 완료하면 다음을 할 수 있습니다:

  • SSH 키 없이 안전한 배포 파이프라인 구축
  • 명령어 수준의 세밀한 권한 제어
  • 자동화된 빌드 및 배포 프로세스 구현

사전 준비사항

Step 1: API 토큰 생성 (2분)

1-1. 워크스페이스 설정으로 이동

  1. Alpacon 워크스페이스에 로그인
  2. 좌측 메뉴에서 Settings > API Tokens 클릭
  3. Create Token 버튼 클릭

1-2. 토큰 권한 설정

토큰 생성 화면에서 다음 정보를 입력합니다:

Token Name: github-actions-deploy
Token Type: Deployment Token
Expiry: 90 days (권장)
 
Command ACL:
  - git pull origin main
  - npm ci
  - npm run build
  - pm2 restart app
  - pm2 status
  - systemctl status nginx

💡 팁: 개발과 프로덕션용 토큰을 분리하여 관리하세요.

1-3. 토큰 저장

  1. Create 클릭
  2. 생성된 토큰을 안전한 곳에 복사 (한 번만 표시됨!)

Step 2: GitHub 저장소 설정 (3분)

2-1. GitHub Secrets 추가

GitHub 저장소에서:

  1. Settings > Secrets and variables > Actions 이동
  2. New repository secret 클릭
  3. 다음 시크릿 추가:
NameValue
ALPACON_WORKSPACE_URLhttps://alpacon.io/your-workspace/
ALPACON_API_TOKENStep 1에서 생성한 토큰

2-2. 워크플로우 파일 생성

저장소 루트에 .github/workflows 디렉토리 생성 후:

.github/workflows/deploy.yml:

name: Deploy to Production
 
on:
  push:
    branches: [main]
 
env:
  NODE_VERSION: '18'
 
jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v3
 
    - name: Setup Node.js
      uses: actions/setup-node@v3
      with:
        node-version: ${{ env.NODE_VERSION }}
        cache: 'npm'
 
    - name: Install dependencies
      run: npm ci
 
    - name: Run tests
      run: npm test
 
    - name: Build application
      run: npm run build
 
    # 빌드 결과물을 아티팩트로 저장
    - name: Upload build artifacts
      uses: actions/upload-artifact@v3
      with:
        name: build-artifacts
        path: dist/
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
 
    steps:
    # 빌드 아티팩트 다운로드
    - name: Download artifacts
      uses: actions/download-artifact@v3
      with:
        name: build-artifacts
        path: dist/
 
    # Alpacon CLI 설치
    - name: Setup Alpacon CLI
      uses: alpacax/alpacon-setup-action@v1.0.0
 
    # 빌드 결과물을 서버로 전송
    - name: Upload to server
      uses: alpacax/alpacon-cp-action@v1.0.0
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_API_TOKEN }}
        source: './dist/'
        target-server: 'prod-server'
        target-path: '/var/www/app/dist/'
        recursive: true
 
    # 애플리케이션 재시작
    - name: Restart application
      uses: alpacax/alpacon-websh-action@v1.0.0
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_API_TOKEN }}
        target: 'prod-server'
        script: |
          pm2 restart app
          pm2 status
 
    # 헬스 체크
    - name: Health check
      uses: alpacax/alpacon-websh-action@v1.0.0
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_API_TOKEN }}
        target: 'prod-server'
        script: |
          curl -f http://localhost:3000/health || exit 1

Step 3: 첫 배포 실행 (2분)

3-1. 코드 푸시

git add .github/workflows/deploy.yml
git commit -m "Add CI/CD pipeline with Alpacon"
git push origin main

3-2. 배포 모니터링

  1. GitHub 저장소의 Actions 탭 이동
  2. 실행 중인 워크플로우 클릭
  3. 각 단계별 로그 확인

3-3. Alpacon에서 확인

  1. Alpacon 워크스페이스의 Monitoring 이동
  2. 실행된 명령어와 결과 확인
  3. 감사 로그에서 API 토큰 사용 내역 확인

Step 4: 고급 설정 (선택사항)

환경별 배포

.github/workflows/deploy-multi-env.yml:

name: Multi-Environment Deploy
 
on:
  push:
    branches: [main, develop]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
 
    steps:
    - uses: actions/checkout@v3
 
    - name: Setup Alpacon CLI
      uses: alpacax/alpacon-setup-action@v1.0.0
 
    # 브랜치별 환경 설정
    - name: Set environment
      id: env
      run: |
        if [[ "${{ github.ref }}" == "refs/heads/main" ]]; then
          echo "target=prod-server" >> $GITHUB_OUTPUT
          echo "token=${{ secrets.ALPACON_PROD_TOKEN }}" >> $GITHUB_OUTPUT
        else
          echo "target=dev-server" >> $GITHUB_OUTPUT
          echo "token=${{ secrets.ALPACON_DEV_TOKEN }}" >> $GITHUB_OUTPUT
        fi
 
    - name: Deploy to ${{ steps.env.outputs.target }}
      uses: alpacax/alpacon-websh-action@v1.0.0
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ steps.env.outputs.token }}
        target: ${{ steps.env.outputs.target }}
        script: |
          cd /app
          git pull
          npm ci
          npm run build
          pm2 restart app

롤백 워크플로우

.github/workflows/rollback.yml:

name: Rollback Deployment
 
on:
  workflow_dispatch:
    inputs:
      version:
        description: 'Version to rollback to'
        required: true
        default: 'previous'
 
jobs:
  rollback:
    runs-on: ubuntu-latest
 
    steps:
    - name: Setup Alpacon CLI
      uses: alpacax/alpacon-setup-action@v1.0.0
 
    - name: Rollback application
      uses: alpacax/alpacon-websh-action@v1.0.0
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_API_TOKEN }}
        target: 'prod-server'
        script: |
          cd /app
          if [ "${{ github.event.inputs.version }}" = "previous" ]; then
            git reset --hard HEAD~1
          else
            git reset --hard ${{ github.event.inputs.version }}
          fi
          npm ci
          npm run build
          pm2 restart app

문제 해결

배포 실패 시

  1. GitHub Actions 로그 확인

    • Actions 탭에서 실패한 단계 확인
    • 에러 메시지 확인

  2. Alpacon 모니터링 확인

    • 명령어 실행 로그 확인
    • 서버 연결 상태 확인

  3. 토큰 권한 확인

    • 필요한 명령어가 ACL에 포함되어 있는지 확인
    • 토큰 만료 여부 확인

일반적인 문제

문제원인해결 방법
Permission denied토큰 ACL에 명령어 없음토큰 권한 업데이트
Server not found잘못된 서버 이름워크스페이스에서 서버 이름 확인
Token expired토큰 만료새 토큰 생성 및 GitHub Secret 업데이트

다음 단계

요약

이 튜토리얼에서 다음을 완료했습니다:

✅ API 토큰 생성 및 권한 설정 ✅ GitHub Secrets 구성 ✅ CI/CD 파이프라인 작성 ✅ 자동 배포 실행 및 모니터링

SSH 키 대신 API 토큰을 사용하여 더 안전하고 관리하기 쉬운 배포 파이프라인을 구축했습니다.