GitHub Actions integration

Automate deployments and server management with Alpacon’s purpose-built GitHub Actions.

Available actions

Alpacon provides four GitHub Actions for CI/CD workflows:

Quick start

1. Generate API token

In your AlpacaX workspace settings:

1. Go to Settings → API Tokens
2. Click “Create Token”
3. Add allowed commands (e.g., git pull, npm install, pm2 restart app)
4. Copy the generated token

2. Add secrets to GitHub

Add these secrets to your repository (Settings → Secrets → Actions):

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

3. Use in workflow

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

Alternative: using Alpacon CLI container

If you prefer to use the Alpacon CLI directly without the pre-built actions, you can use the official Docker container:

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/

This approach provides direct CLI access with minimal setup and is useful for complex workflows requiring multiple CLI commands.

Usage examples

Execute commands as 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

Upload build artifacts

- 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

Download logs

- 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/

Multi-server deployment

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

Run any Alpacon command

- 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 deployment with environment selection

Deploy containerized applications to different environments with dynamic server selection:

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

Action reference

alpacon-setup-action

Installs the Alpacon CLI in your workflow environment.

Inputs: None

Example:

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

alpacon-websh-action

Execute shell commands on remote servers.

Inputs:

alpacon-cp-action

Copy files between local and remote servers.

Inputs:

alpacon-common-action

Run any Alpacon CLI command.

Inputs:

Best practices

• Create dedicated tokens for CI/CD with minimal permissions
• Use command ACL to restrict which commands tokens can execute
• Store tokens as secrets—never commit them to your repository
• Rotate tokens regularly in workspace, then update GitHub secrets
• Use organization secrets for tokens shared across repositories

Resources

• Alpacon CLI documentation
• GitHub Marketplace - Setup Action
• GitHub Marketplace - WebSH Action
• GitHub Marketplace - CP Action
• GitHub Marketplace - Common Action

Next steps

• GitLab CI integration
• Jenkins integration
• API automation
• CLI reference