Technical

Jenkins Start Build Machine From Item: Use the Proxmox API, Not an Old Plugin

Jenkins Start Build Machine From Item: Use the Proxmox API, Not an Old Plugin

Jenkins start build machine from item is just a matter of hitting the Proxmox API. The old plugin everyone recommends is from 2016 and barely works with modern Jenkins. Here’s the fix.

Detailed close-up of ethernet cables and network connections on a router, showcasing modern technology.

Why the plugin is a dead end

The “Proxmox Plugin” for Jenkins hasn’t been updated in years. It breaks on newer Jenkins versions, and the UI is clunky. You don’t need it. Proxmox has a clean REST API, and Jenkins can call it with a simple shell step.

Get an API token

First, create an API token in Proxmox. Go to Datacenter → Permissions → API Tokens. Add a token for your user, and don’t select “Privilege Separation” — keep it simple for a homelab. Copy the token ID and secret. You’ll use them in Jenkins credentials.

Electric blue wires connected to network adapter plugged in socket on shabby brown wall of building on street with shado

Store credentials in Jenkins

In Jenkins, add a new credential of type “Username with password”. Username is your Proxmox user, password is the API token secret. Give it an ID like proxmox-api.

The pipeline step

In your Jenkinsfile, add a stage that calls the Proxmox API to start the VM. Replace NODE, VMID, and the credential ID with your own.

stage('Start Build VM') {
    steps {
        withCredentials([usernamePassword(credentialsId: 'proxmox-api', usernameVariable: 'PROXMOX_USER', passwordVariable: 'PROXMOX_PASS')]) {
            sh '''
                curl -k -X POST https://proxmox:8006/api2/json/nodes/${NODE}/qemu/${VMID}/status/start \
                    -H "Authorization: PVEAPIToken=${PROXMOX_USER}!token-id=${PROXMOX_PASS}"
            '''
        }
    }
}

That’s it. The VM boots, and Jenkins can continue. If you want to wait until the VM is actually up, add a loop that polls the API for the VM status. Or just sleep for a bit — it’s a homelab, not a bank.

Why this beats the plugin

No plugin dependency, no UI to fight. You control exactly when the VM starts, and you can extend it to stop the VM after the build. The API is the same one Proxmox uses for everything else, so you’re not learning a new tool.

If you’re doing this with cloud-init images, make sure the VM is set up to accept SSH keys. I wrote about cloud-init only creating the default user — that’ll bite you if you’re not careful.

Leave a comment

Comments are reviewed before they appear. Your email is never published.