GitHub Actions 통합

Alpacon의 전용 GitHub Actions로 배포와 서버 관리를 자동화하세요.

사용 가능한 액션

Alpacon은 CI/CD 워크플로를 위한 4가지 GitHub Actions를 제공합니다:

액션용도사용 사례
[alpacon-setup-action]Alpacon CLI 설치항상 먼저 실행
[alpacon-websh-action]원격 명령 실행앱 배포, 서비스 재시작
[alpacon-cp-action]파일 전송빌드 업로드, 로그 다운로드
[alpacon-common-action]모든 Alpacon 명령 실행서버 목록 조회, 상태 확인

빠른 시작

1. API 토큰 생성

AlpacaX 워크스페이스 설정에서:

  1. Settings → API Tokens로 이동
  2. “Create Token” 클릭
  3. 허용된 명령 추가 (예: git pull, npm install, pm2 restart app)
  4. 생성된 토큰 복사

2. GitHub에 시크릿 추가

리포지토리에 다음 시크릿을 추가하세요 (Settings → Secrets → Actions):

ALPACON_WORKSPACE_URL: https://your-workspace.us1.alpacon.io
ALPACON_API_TOKEN: your-token-here

3. 워크플로에서 사용

name: Deploy with Alpacon
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Alpacon CLI
        uses: alpacax/alpacon-setup-action@v1.0.0
 
      - name: Deploy to production
        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
            git pull
            npm install
            pm2 restart app

대안: Alpacon CLI 컨테이너 사용

사전 제작된 액션 대신 Alpacon CLI를 직접 사용하려면 공식 Docker 컨테이너를 사용할 수 있습니다:

name: Deploy with Alpacon CLI
on:
  push:
    branches: [main]
 
jobs:
  deploy:
    runs-on: ubuntu-latest
    container:
      image: alpacax/alpacon-cli:latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Login to Alpacon
        run: alpacon login ${{ secrets.ALPACON_WORKSPACE_URL }} -t ${{ secrets.ALPACON_API_TOKEN }}
 
      - name: Deploy to production
        run: |
          alpacon websh prod-server "cd /app && git pull && npm install && pm2 restart app"
 
      - name: Upload build artifacts
        run: |
          alpacon cp -r ./dist/ prod-server:/var/www/app/

이 방식은 최소한의 설정으로 CLI에 직접 접근할 수 있으며, 여러 CLI 명령이 필요한 복잡한 워크플로에 유용합니다.

사용 예제

root 권한으로 명령 실행

- name: Restart nginx
  uses: alpacax/alpacon-websh-action@v1.0.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'web-server'
    script: systemctl restart nginx
    as-root: true

빌드 산출물 업로드

- name: Build application
  run: npm run build
 
- name: Upload build 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/'
    recursive: true

로그 다운로드

- name: Download error logs
  uses: alpacax/alpacon-cp-action@v1.0.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    source: '/var/log/app/error.log'
    target-server: 'prod-server'
    target-path: './logs/'
    mode: download
 
- name: Upload logs as artifact
  uses: actions/upload-artifact@v4
  with:
    name: error-logs
    path: ./logs/

다중 서버 배포

jobs:
  deploy:
    runs-on: ubuntu-latest
    strategy:
      matrix:
        server: [web1, web2, web3]
    steps:
      - uses: actions/checkout@v4
 
      - name: Setup Alpacon CLI
        uses: alpacax/alpacon-setup-action@v1.0.0
 
      - name: Deploy to ${{ matrix.server }}
        uses: alpacax/alpacon-websh-action@v1.0.0
        with:
          workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
          api-token: ${{ secrets.ALPACON_API_TOKEN }}
          target: ${{ matrix.server }}
          script: |
            cd /app
            git pull
            npm install
            pm2 restart app

모든 Alpacon 명령 실행

- name: List all servers
  uses: alpacax/alpacon-common-action@v1.0.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    command: "server ls"

환경별 Docker 배포

동적 서버 선택을 통해 다양한 환경에 컨테이너화된 애플리케이션을 배포합니다:

name: Deploy Application
 
on:
  workflow_dispatch:
    inputs:
      env:
        description: "Deployment environment"
        required: true
        type: choice
        options:
          - dev
          - prod
 
jobs:
  deploy:
    runs-on: ubuntu-latest
 
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
 
      - name: Select target server
        run: |
          if [ "${{ inputs.env }}" = "prod" ]; then
            echo "TARGET_SERVER=prod-server" >> $GITHUB_ENV
            echo "APP_PORT=8080" >> $GITHUB_ENV
          else
            echo "TARGET_SERVER=dev-server" >> $GITHUB_ENV
            echo "APP_PORT=8081" >> $GITHUB_ENV
          fi
 
      - name: Prepare environment file
        run: |
          echo "APP_ENV=${{ inputs.env }}" > /tmp/.env
          echo "APP_PORT=${{ env.APP_PORT }}" >> /tmp/.env
          echo '${{ secrets.APP_SECRETS }}' >> /tmp/.env
 
      - name: Setup Alpacon CLI
        uses: alpacax/alpacon-setup-action@v1.0.0
 
      - name: Docker login on target server
        uses: alpacax/alpacon-websh-action@v1.0.0
        with:
          workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
          api-token: ${{ secrets.ALPACON_API_TOKEN }}
          target: ${{ env.TARGET_SERVER }}
          script: docker login -u ${{ secrets.DOCKER_USERNAME }} -p ${{ secrets.DOCKER_PASSWORD }}
 
      - name: Copy docker-compose.yml
        uses: alpacax/alpacon-cp-action@v1.0.0
        with:
          workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
          api-token: ${{ secrets.ALPACON_API_TOKEN }}
          source: ./docker-compose.yml
          target-server: ${{ env.TARGET_SERVER }}
          target-path: /opt/myapp/docker-compose.yml
 
      - name: Copy environment file
        uses: alpacax/alpacon-cp-action@v1.0.0
        with:
          workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
          api-token: ${{ secrets.ALPACON_API_TOKEN }}
          source: /tmp/.env
          target-server: ${{ env.TARGET_SERVER }}
          target-path: /opt/myapp/.env
 
      - name: Deploy application
        uses: alpacax/alpacon-websh-action@v1.0.0
        with:
          workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
          api-token: ${{ secrets.ALPACON_API_TOKEN }}
          target: ${{ env.TARGET_SERVER }}
          script: |
            docker compose -f /opt/myapp/docker-compose.yml pull
            docker compose -f /opt/myapp/docker-compose.yml --env-file /opt/myapp/.env up -d
            docker compose -f /opt/myapp/docker-compose.yml ps

액션 레퍼런스

alpacon-setup-action

워크플로 환경에 Alpacon CLI를 설치합니다.

입력값: 없음

예제:

- name: Setup Alpacon CLI
  uses: alpacax/alpacon-setup-action@v1.0.0

alpacon-websh-action

원격 서버에서 쉘 명령을 실행합니다.

입력값:

이름설명필수기본값
workspace-urlAlpacaX 워크스페이스 URL예
api-tokenAlpacon API 토큰예
target대상 서버 이름예
script실행할 쉘 명령 또는 스크립트예
as-rootroot 사용자로 명령 실행아니오false

alpacon-cp-action

로컬과 원격 서버 간 파일을 복사합니다.

입력값:

이름설명필수기본값
workspace-urlAlpacaX 워크스페이스 URL예
api-tokenAlpacon API 토큰예
source소스 경로예
target-server대상 서버 이름예
target-path목적지 경로예
modeupload 또는 download아니오upload
recursive디렉토리를 재귀적으로 복사아니오false

alpacon-common-action

모든 Alpacon CLI 명령을 실행합니다.

입력값:

이름설명필수
workspace-urlAlpacaX 워크스페이스 URL예
api-tokenAlpacon API 토큰예
command실행할 Alpacon 명령예

모범 사례

  • 최소 권한을 가진 CI/CD 전용 토큰을 생성하세요
  • 토큰이 실행할 수 있는 명령을 제한하기 위해 명령 ACL을 사용하세요
  • 토큰을 시크릿으로 저장하세요—절대 리포지토리에 커밋하지 마세요
  • 워크스페이스에서 정기적으로 토큰을 갱신한 후 GitHub 시크릿을 업데이트하세요
  • 리포지토리 간 공유되는 토큰에는 조직 시크릿을 사용하세요

출처

다음 단계