GitLab Proxmox Executor

A custom GitLab Runner executor for running CI/CD jobs inside ephemeral Proxmox VMs.

Each job gets a fresh VM clone, runs isolated, and is cleaned up automatically.

---

Quick Start

1) Prepare Proxmox Template

Use a VM template with:

• qemu-guest-agent installed and running
• SSH enabled
• Password-based login for initial runner access

For full template hardening and conversion steps, see docs/advanced-usage.md.

2) Install Executor Binary

# Linux amd64
curl -L -o gitlab-proxmox-executor \
  https://github.com/wibu-systems/gitlab-proxmox-executor/releases/latest/download/gitlab-proxmox-executor-linux-amd64

chmod +x gitlab-proxmox-executor
sudo mv gitlab-proxmox-executor /usr/local/bin/

3) Run on Native Proxmox Host

# Install GitLab Runner
curl -L https://packages.gitlab.com/install/repositories/runner/gitlab-runner/script.deb.sh | sudo bash
sudo apt-get update
sudo apt-get install -y gitlab-runner

# Ensure config directory exists
sudo mkdir -p /etc/gitlab-runner

Create or update /etc/gitlab-runner/config.toml with the example below, then restart:

sudo systemctl restart gitlab-runner
sudo systemctl status gitlab-runner --no-pager

4) Run in Kubernetes Cluster

Use the dedicated deployment guide in deploy/kubernetes/README.md.

---

Minimal Configuration

config.toml

concurrent = 2

[[runners]]
  name = "proxmox-runner"
  url = "https://gitlab.example.com"
  token = "YOUR_TOKEN"
  executor = "custom"
  tags = ["proxmox"]

  [runners.custom]
    config_exec  = "gitlab-proxmox-executor"
    config_args  = ["config"]
    prepare_exec = "gitlab-proxmox-executor"
    prepare_args = ["prepare"]
    run_exec     = "gitlab-proxmox-executor"
    run_args     = ["run"]
    cleanup_exec = "gitlab-proxmox-executor"
    cleanup_args = ["cleanup"]

  environment = [
    "PROXMOX_URL=https://proxmox.example.com:8006/api2/json",
    "PROXMOX_TOKEN_ID=user@pam!token-name",
    "PROXMOX_TOKEN_SECRET=CHANGE_ME",
    "PROXMOX_TEMPLATE_NAME=lin-tmpl",
    # Alternative:
    # "PROXMOX_TEMPLATE_VMID=30002",
    "PROXMOX_SSH_USER=ci",
    "PROXMOX_SSH_PASS=CHANGE_ME",
    "PROXMOX_KEEP_VM_ON_FAILURE=30m",
  ]

Required environment variables:

• PROXMOX_URL
• PROXMOX_TOKEN_ID and PROXMOX_TOKEN_SECRET (or user/password auth)
• PROXMOX_TEMPLATE_NAME or PROXMOX_TEMPLATE_VMID
• PROXMOX_SSH_USER and PROXMOX_SSH_PASS

See full variable reference in docs/advanced-usage.md.

---

Example .gitlab-ci.yml Job

test-installer:
  tags:
    - proxmox
  variables:
    PROXMOX_TEMPLATE_NAME: "lin-tmpl"
    PROXMOX_NETWORK: "default"
    PROXMOX_KEEP_VM_ON_FAILURE: "30m"
  script:
    - sudo dpkg -i ./build/myapp_1.0.0_amd64.deb
    - myapp --version

---

Day-2 Operations

For advanced operations and troubleshooting, see:

• docs/advanced-usage.md
• deploy/kubernetes/README.md
• Proxmox.md

Topics covered in the advanced guide:

• Full environment variable reference
• Network formats and clone modes
• Keep failed VMs alive and automatic cleanup
• Cluster mode behavior
• Integration test setup
• Public repository safety checklist

---

Commands

Command	Description
gitlab-proxmox-executor config	Output runner config for GitLab Runner
gitlab-proxmox-executor prepare	Clone and start VM
gitlab-proxmox-executor run <script>	Execute script in VM via SSH
gitlab-proxmox-executor cleanup	Stop/delete VM or mark keep-alive
gitlab-proxmox-executor cleanup-expired	Delete expired failed VMs
gitlab-proxmox-executor --version	Show version

---

Contributing

Contributions and testing feedback are welcome.

---

Third-Party Licenses (Container Images)

This project distributes container images that include third-party software.

See THIRD_PARTY_NOTICES.md for a component summary and upstream license references.

Container images include third-party components under their respective licenses.

---

License

MIT - see LICENSE.

Based on gitlab-tart-executor by Cirrus Labs (MIT License).