Jenkins integration

Integrate Alpacon into Jenkins pipelines using the official Docker container.

Prerequisites

Jenkins with Docker Pipeline plugin
Alpacon workspace and API token

Quick start

1. Add credentials

In Manage Jenkins → Credentials, add:

ALPACON_WORKSPACE_URL: https://your-workspace.us1.alpacon.io (Secret text)
ALPACON_API_TOKEN: Your API token (Secret text)

2. Create pipeline

pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE_URL = credentials('ALPACON_WORKSPACE_URL')
        ALPACON_API_TOKEN = credentials('ALPACON_API_TOKEN')
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN'
                sh 'alpacon websh prod-server "cd /opt/myapp && git pull && pm2 restart app"'
            }
        }
    }
}

Important: args '--entrypoint=""' is required to override the container’s default entrypoint.

Usage examples

Deploy application

pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE_URL = credentials('ALPACON_WORKSPACE_URL')
        ALPACON_API_TOKEN = credentials('ALPACON_API_TOKEN')
        TARGET_SERVER = 'prod-server'
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN'
                sh 'alpacon websh $TARGET_SERVER "cd /opt/myapp && git pull origin main"'
                sh 'alpacon websh $TARGET_SERVER "cd /opt/myapp && npm ci --omit=dev"'
                sh 'alpacon websh $TARGET_SERVER "pm2 restart myapp"'
            }
        }
    }
}

Restart services as root

pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE_URL = credentials('ALPACON_WORKSPACE_URL')
        ALPACON_API_TOKEN = credentials('ALPACON_API_TOKEN')
    }
 
    stages {
        stage('Restart') {
            steps {
                sh 'alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN'
                sh 'alpacon websh root@prod-server "systemctl restart nginx"'
                sh 'alpacon websh root@prod-server "systemctl status nginx"'
            }
        }
    }
}

Deploy with Docker Compose

pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE_URL = credentials('ALPACON_WORKSPACE_URL')
        ALPACON_API_TOKEN = credentials('ALPACON_API_TOKEN')
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN'
                sh 'alpacon cp docker-compose.yml prod-server:/opt/myapp/docker-compose.yml'
                sh 'alpacon cp .env prod-server:/opt/myapp/.env'
                sh 'alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml pull"'
                sh 'alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml up -d"'
                sh 'alpacon websh root@prod-server "docker compose -f /opt/myapp/docker-compose.yml ps"'
            }
        }
    }
}

Security

All commands executed through Alpacon are recorded in the workspace audit log. Sensitive values (such as passwords and tokens) passed via environment variables are automatically masked in command history.

Troubleshooting

Entrypoint error

Symptom: Container doesn’t run the expected command

Solution: Make sure to include args '--entrypoint=""' in docker agent configuration.