GitLab CI integration

Automate deployments and server management with Alpacon in GitLab CI/CD pipelines using the official Docker container.

Quick start

1. Generate API token

In your Alpacon workspace settings:

  1. Go to Settings → API Tokens
  2. Click “Create Token”
  3. Add allowed commands for your deployment needs
  4. Copy the generated token

2. Add CI/CD variables

Add these variables to your GitLab project (Settings → CI/CD → Variables):

  • ALPACON_WORKSPACE_URL: Your workspace URL (e.g., https://your-workspace.us1.alpacon.io)
  • ALPACON_API_TOKEN: Your API token (mark as Masked and Protected)

3. Create .gitlab-ci.yml

IMPORTANT: The alpacax/alpacon-cli image has ENTRYPOINT ["alpacon"] set, so you must override it with entrypoint: [""] in GitLab CI.

stages:
  - deploy
 
deploy:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    - alpacon websh -r prod-server "docker ps"
  only:
    - main

Usage examples

Deploy with docker-compose.yml

deploy-compose:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    - alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
    - alpacon websh -r prod-server "docker compose -f /tmp/app-compose.yml up -d"
    - alpacon websh -r prod-server "docker ps"
  only:
    - main

Deploy with environment file

Note: When uploading multiple files to a directory, you need to create the directory first and set proper permissions:

deploy-with-env:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    # Create directory with proper permissions
    - alpacon websh -r prod-server "mkdir -p /tmp/myapp && chown $USER:$USER /tmp/myapp"
    # Upload files
    - alpacon cp docker-compose.yml prod-server:/tmp/myapp/
    - alpacon cp .env prod-server:/tmp/myapp/
    # Deploy
    - alpacon websh -r prod-server "docker compose -f /tmp/myapp/docker-compose.yml up -d"
    - alpacon websh -r prod-server "docker ps"
  only:
    - main

Deploy with image tag

deploy-tagged:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    - alpacon websh -r prod-server "docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD"
    - alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
    - alpacon websh -r --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" prod-server "docker compose -f /tmp/app-compose.yml up -d"
  only:
    - main

Multi-environment deployment

deploy-staging:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    - alpacon cp docker-compose.yml staging-server:/tmp/app-compose.yml
    - alpacon websh -r staging-server "docker compose -f /tmp/app-compose.yml up -d"
  only:
    - develop
  environment:
    name: staging
 
deploy-production:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    - alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
    - alpacon websh -r prod-server "docker compose -f /tmp/app-compose.yml up -d"
  only:
    - main
  environment:
    name: production
  when: manual

Complete CI/CD pipeline

stages:
  - build
  - deploy
 
build-image:
  stage: build
  image: docker:latest
  services:
    - docker:dind
  script:
    - docker login -u $DOCKER_USERNAME -p $DOCKER_PASSWORD
    - docker build -t $DOCKER_USERNAME/myapp:$CI_COMMIT_SHORT_SHA .
    - docker push $DOCKER_USERNAME/myapp:$CI_COMMIT_SHORT_SHA
  only:
    - main
 
deploy:
  stage: deploy
  image:
    name: alpacax/alpacon-cli:latest
    entrypoint: [""]
  script:
    - alpacon login $ALPACON_WORKSPACE_URL -t $ALPACON_API_TOKEN
    - alpacon websh -r --env="DOCKER_USERNAME=$DOCKER_USERNAME" --env="DOCKER_PASSWORD=$DOCKER_PASSWORD" prod-server "docker login -u \$DOCKER_USERNAME -p \$DOCKER_PASSWORD"
    - alpacon cp docker-compose.yml prod-server:/tmp/app-compose.yml
    - alpacon websh -r --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" prod-server "docker compose -f /tmp/app-compose.yml pull"
    - alpacon websh -r --env="IMAGE_TAG=$CI_COMMIT_SHORT_SHA" --env="DOCKER_USERNAME=$DOCKER_USERNAME" prod-server "docker compose -f /tmp/app-compose.yml up -d"
    - alpacon websh -r prod-server "docker ps"
  only:
    - main
  needs:
    - build-image

Troubleshooting

Entrypoint error

Symptom: Error: unknown command "sh" for "alpacon"

Solution: You forgot to add entrypoint: [""] to the image configuration. Use:

image:
  name: alpacax/alpacon-cli:latest
  entrypoint: [""]

Permission denied

Symptom: permission denied when running Docker commands

Solution: Add -r flag to run as root: alpacon websh -r server-name "docker ps"

File not found after upload

Symptom: File uploaded successfully but not found when executing commands

Solution: The directory may not exist or you don’t have permissions. Create the directory with proper ownership:

- alpacon websh -r server "mkdir -p /path/to/dir && chown username:username /path/to/dir"
- alpacon cp file.txt server:/path/to/dir/

Resources

Next steps