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:

Action	Purpose	Use case
[alpacon-setup-action]	Install Alpacon CLI	Always run first
[alpacon-websh-action]	Execute remote commands	Deploy apps, restart services
[alpacon-cp-action]	Transfer files	Upload builds, download logs
[alpacon-common-action]	Run any Alpacon command	List servers, check status

Quick start

1. Generate API token

In your Alpacon workspace settings:

Go to Settings → API Tokens
Click “Create Token”
Add allowed commands (e.g., git pull, npm install, pm2 restart app)
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.1.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.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'web-server'
    username: 'root'
    script: systemctl restart nginx

Execute commands as specific user

- name: Deploy as ubuntu user
  uses: alpacax/alpacon-websh-action@v1.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'web-server'
    username: 'ubuntu'
    script: |
      cd /home/ubuntu/app
      git pull
      npm install

Execute commands with specific user and group

- name: Deploy with www-data group
  uses: alpacax/alpacon-websh-action@v1.1.0
  with:
    workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
    api-token: ${{ secrets.ALPACON_API_TOKEN }}
    target: 'web-server'
    username: 'ubuntu'
    groupname: 'www-data'
    script: cp -r /tmp/build/* /var/www/html/

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.1.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.1.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.1.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:

Name	Description	Required
`workspace-url`	Your Alpacon workspace URL	Yes
`api-token`	Alpacon API token	Yes
`target`	Target server name	Yes
`script`	Shell command or script to execute	Yes
`username`	Username to execute the command as (e.g., root, ubuntu)	No
`groupname`	Group name to execute the command as (requires username)	No

alpacon-cp-action

Copy files between local and remote servers.

Inputs:

Name	Description	Required	Default
`workspace-url`	Your Alpacon workspace URL	Yes
`api-token`	Alpacon API token	Yes
`source`	Source path	Yes
`target-server`	Target server name	Yes
`target-path`	Destination path	Yes
`mode`	`upload` or `download`	No	`upload`
`recursive`	Copy directories recursively	No	`false`

alpacon-common-action

Run any Alpacon CLI command.

Inputs:

Name	Description	Required
`workspace-url`	Your Alpacon workspace URL	Yes
`api-token`	Alpacon API token	Yes
`command`	Alpacon command to execute	Yes

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

GitHub Actions integration

Available actions

Quick start

1. Generate API token

2. Add secrets to GitHub

3. Use in workflow

Alternative: using Alpacon CLI container

Usage examples

Execute commands as root

Execute commands as specific user

Execute commands with specific user and group

Upload build artifacts

Download logs

Multi-server deployment

Run any Alpacon command

Docker deployment with environment selection

Action reference

alpacon-setup-action

alpacon-websh-action

alpacon-cp-action

alpacon-common-action

Best practices

Resources

Next steps