Jenkins integration

Integrate Alpacon into Jenkins pipelines using the official Docker container.

Prerequisites

  • Jenkins with Docker Pipeline plugin
  • An Alpacon workspace, and the application the pipeline’s service token will belong to

A workspace on the Free plan holds one application, so the pipeline shares the one already there rather than getting its own.

Quick start

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. Go to IAM → Applications and open the application this pipeline belongs to, or create one.
  2. Open the Credentials tab and click Add.
  3. Name the token, choose its scopes, and write the reason it is needed.
  4. Copy the key when it is shown. It starts with alpst-, and it is shown only once.

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.

2. Add the ACL rules

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

Open the token, go to its ACL tab, and add:

RuleWhat it bounds
Server ACLWhich servers the pipeline may reach
Command ACLWhich commands it may run, for example git pull, npm ci, pm2 restart myapp
File ACLWhich paths it may upload to or download from

A file transfer checks the server rule first, then the file rule. Skip the ACL tab and the pipeline fails on its first command.

3. Add credentials

In Manage Jenkins → Credentials, add:

  • ALPACON_WORKSPACE: Your workspace name, for example your-workspace (Secret text)
  • ALPACON_REGION: Your workspace region, us1 or ap1 (Secret text)
  • ALPACON_SERVICE_TOKEN: The alpst- key from step 1 (Secret text)

4. Create pipeline

pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_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.

The CLI reads the token from alpacon login only. There is no environment-variable auth path, so every pipeline keeps that login step before the first Alpacon command.

Usage examples

Deploy application

pipeline {
    agent {
        docker {
            image 'alpacax/alpacon-cli:latest'
            args '--entrypoint=""'
        }
    }
 
    environment {
        ALPACON_WORKSPACE = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
        TARGET_SERVER = 'prod-server'
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_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 = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
    }
 
    stages {
        stage('Restart') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_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 = credentials('ALPACON_WORKSPACE')
        ALPACON_REGION = credentials('ALPACON_REGION')
        ALPACON_SERVICE_TOKEN = credentials('ALPACON_SERVICE_TOKEN')
    }
 
    stages {
        stage('Deploy') {
            steps {
                sh 'alpacon login --workspace $ALPACON_WORKSPACE --region $ALPACON_REGION -t $ALPACON_SERVICE_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"'
            }
        }
    }
}

The two alpacon cp lines need a File ACL entry for /opt/myapp/ on top of the Server ACL entry, and the docker compose lines need Command ACL entries.

Security

All commands executed through Alpacon are recorded in the workspace audit log, attributed to the application that owns the token rather than to a person. 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.

Login fails on a valid service token

Symptom: alpacon login reports failed to verify user profile, even though the alpst- key was copied correctly

Solution: Service tokens need Alpacon CLI v1.7.4 or later. An older CLI doesn’t recognize the alpst- key and reports this misleading message instead. Check the version your agent actually runs—a self-hosted agent or a pinned alpacax/alpacon-cli image tag is the usual cause—and upgrade it.

Command or file refused

Symptom: A command or alpacon cp that works from your own terminal is refused in the pipeline

Solution: The token’s ACL doesn’t cover it. Add the missing Server, Command, or File ACL entry on the token’s ACL tab; each of the three is deny-by-default, so a rule you never added blocks everything of that kind.

Next steps

Last updated: