Deploy your first change with GitHub Actions

Step-by-step tutorial for building a CI/CD pipeline using Alpacon GitHub Actions.

Learning objectives#

After completing this tutorial, you’ll be able to:

• Build secure deployment pipelines without SSH keys
• Implement fine-grained command-level access control
• Create automated build and deployment processes

Prerequisites#

• Alpacon workspace ready
• Server registered and agent installed
• An application for this pipeline, or administrator access to create one
• GitHub repository access

Step 1: Create a service token (5 min + approval wait)#

1-1. Create a service token#

CI and automation run on service tokens. A service token belongs to an application rather than to a person, so it survives staff changes, and its ACL bounds exactly what the pipeline may do.

1. Log in to your Alpacon workspace
2. Go to IAM → Applications and open the application this pipeline belongs to, or create one
3. Open the Tokens tab and click Create token

Work through the four steps:

Purpose: name github-actions-deploy, expires in 30 days
Permissions: start from the Deploy pipeline template, then adjust
Access rules: prod-server and the upload path listed in 1-2
Review: write why this pipeline needs the token

Expiry defaults to 30 days, and you can pick 90 days, 365 days, or a custom time instead. Service tokens must expire, but the workspace maximum token lifetime does not apply to them.

The key appears once, hidden, when you select Create token. It starts with alpst-. Copy or download it, then check I’ve stored the key somewhere safe to close the dialog.

A token scoped for CI is reviewed before it works: the request is created as pending and authenticates nowhere until someone with approval rights activates it. Allow for that step rather than discovering it mid-pipeline.

1-2. Add the ACL rules#

A new service token reaches nothing until its ACL rules are applied. Servers, commands, and file paths are each deny-by-default, so a token with no rules is refused everywhere.

The rules you chose in the Access rules step wait on the token until it is approved. After approval, open the token’s Access rules tab and select Apply under Prepared access rules, or add the server and file rules there yourself. On Alpacon Cloud, a Command ACL admins member adds each command below under Pre-approved commands on the same tab. This access is separate from the workspace role. On self-hosted deployments, add each line as a command pattern under Allowed commands on the Access rules tab. Configure:

Each command entry must match a whole submitted line. For the workflows below, add the commands each token needs, one per entry:

pm2 restart app
pm2 status
curl -f http://localhost:3000/health || exit 1
cd /app && git pull && npm ci && npm run build && pm2 restart app
cd /app && if [ "$ROLLBACK_VERSION" = "previous" ]; then git reset --hard HEAD~1; else git reset --hard "$ROLLBACK_VERSION"; fi && npm ci && npm run build && pm2 restart app

A file transfer checks the server rule first, then the file rule, so the Upload to server step needs a Server ACL entry and a File ACL entry, not just one of them.

1-3. Confirm the token is active#

Open the token’s Overview tab and check that its status is no longer pending. A pending token authenticates nowhere, so a pipeline built on it fails at its first Alpacon step.

Step 2: Configure GitHub repository (3 min)#

2-1. Add GitHub Secrets#

In your GitHub repository:

1. Go to Settings > Secrets and variables > Actions
2. Click New repository secret
3. Add the following secrets:

The action input below is named api-token and takes the service token as-is. The name is kept for compatibility with published workflows.

2-2. Create workflow file#

Create .github/workflows directory in repository root:

.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@v4
 
    - name: Setup Node.js
      uses: actions/setup-node@v4
      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
 
    # Save build artifacts
    - name: Upload build artifacts
      uses: actions/upload-artifact@v4
      with:
        name: build-artifacts
        path: dist/
 
  deploy:
    needs: test
    runs-on: ubuntu-latest
    if: github.ref == 'refs/heads/main'
 
    steps:
    # Download build artifacts
    - name: Download artifacts
      uses: actions/download-artifact@v4
      with:
        name: build-artifacts
        path: dist/
 
    # Install Alpacon CLI
    - name: Setup Alpacon CLI
      uses: alpacax/alpacon-setup-action@v1
 
    # Upload build to server
    - name: Upload to server
      uses: alpacax/alpacon-cp-action@v1
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
        source: './dist/'
        target-server: 'prod-server'
        target-path: '/var/www/app/dist/'
        recursive: true
 
    # Restart application
    - name: Restart application
      uses: alpacax/alpacon-websh-action@v1
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
        target: 'prod-server'
        script: |
          pm2 restart app
          pm2 status
 
    # Health check
    - name: Health check
      uses: alpacax/alpacon-websh-action@v1
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
        target: 'prod-server'
        script: |
          curl -f http://localhost:3000/health || exit 1

Step 3: Run first deployment (2 min)#

3-1. Push code#

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

3-2. Monitor deployment#

1. Go to Actions tab in GitHub repository
2. Click on running workflow
3. Check logs for each step

3-3. Verify in Alpacon#

1. Open Audit > Events in your Alpacon workspace
2. Check the Commands tab for executed commands and results, recorded against the application that owns the token
3. Open the token’s Overview tab, where its usage is recorded

Step 4: Advanced configuration (Optional)#

Multi-environment deployment#

.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@v4
 
    - name: Setup Alpacon CLI
      uses: alpacax/alpacon-setup-action@v1
 
    # Set environment based on branch
    - 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
      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

Each of these tokens carries its own ACL, so the development token never needs a Server ACL entry for prod-server.

Rollback workflow#

.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
 
    - name: Rollback application
      uses: alpacax/alpacon-websh-action@v1
      env:
        ROLLBACK_VERSION: ${{ github.event.inputs.version }}
      with:
        workspace-url: ${{ secrets.ALPACON_WORKSPACE_URL }}
        api-token: ${{ secrets.ALPACON_SERVICE_TOKEN }}
        target: 'prod-server'
        env: |
          ROLLBACK_VERSION
        script: |
          cd /app && if [ "$ROLLBACK_VERSION" = "previous" ]; then git reset --hard HEAD~1; else git reset --hard "$ROLLBACK_VERSION"; fi && npm ci && npm run build && pm2 restart app

Troubleshooting#

When deployment fails#

1. Check GitHub Actions logs

   • Check failed step in Actions tab
   • Review error messages

2. Check Alpacon audit events

   • Review command execution logs under Audit > Events
   • Verify server connection status

3. Check the token’s ACL and status

   • Ensure the command has a matching Command ACL entry, and that a file transfer has both a Server ACL and a File ACL entry
   • Check that the token is active rather than still pending, and that it hasn’t expired

Common issues#

Next steps#

• Deployment overview
• Service tokens
• Security best practices
• Monitoring and alerting setup

Summary#

In this tutorial, you completed:

✅ Service token creation and ACL configuration ✅ GitHub Secrets setup ✅ CI/CD pipeline creation ✅ Automated deployment execution and monitoring

You’ve built a safer and more manageable deployment pipeline using a scoped service token instead of SSH keys.