Jenkins: Python API Automation

Table of Contents

• Prerequisites
• Basic Setup
• Update Pipeline Script from Jenkinsfile
• List All Jobs
• Trigger Job with Parameters
• Get Build Console Output
• Copy Job Configuration
• Environment Variables

Automate Jenkins job configuration and execution using the jenkinsapi Python library. This allows you to programmatically manage Jenkins jobs, update configurations, and trigger builds.

Prerequisites

pip install jenkinsapi

Basic Setup

import os
from jenkinsapi.jenkins import Jenkins

# Jenkins connection details
JENKINS_URL = os.environ.get('JENKINS_URL', 'http://localhost:8080')
USERNAME = os.environ.get('JENKINS_USER', os.environ.get('USER'))
API_TOKEN = os.environ.get('JENKINS_API_TOKEN')

# Create Jenkins connection
jenkins = Jenkins(JENKINS_URL, username=USERNAME, password=API_TOKEN, timeout=120)

Update Pipeline Script from Jenkinsfile

This example reads a Jenkinsfile from your repository and updates the Jenkins pipeline job configuration.

import os
import xml.etree.ElementTree as ET
from jenkinsapi.jenkins import Jenkins

def update_pipeline_script(job, jenkinsfile_path):
    """Update Jenkins pipeline job with script from Jenkinsfile"""
    # Read Jenkinsfile content
    with open(jenkinsfile_path, 'r') as file:
        script_content = file.read()

    # Get current job configuration as XML
    config_xml = job.get_config()
    parsed_xml = ET.fromstring(config_xml)

    # Find and update the script element
    # For pipeline jobs, the script is under definition/script
    script_element = parsed_xml.find('definition').find('script')
    if script_element is None:
        raise ValueError("Pipeline script element not found in job configuration")

    script_element.text = script_content

    # Update job configuration
    job.update_config(ET.tostring(parsed_xml, encoding='unicode'))
    print(f"Successfully updated job: {job.name}")

# Usage example
jenkins_url = os.environ.get('JENKINS_URL')
username = os.environ.get('USER')
api_token = os.environ.get('JENKINS_API_TOKEN')

jenkins = Jenkins(jenkins_url, username=username, password=api_token, timeout=120)

# Get job by URL or name
job = jenkins.get_job('my-pipeline-job')
# Or by URL: job = jenkins.get_job_by_url(job_url, job_name='my-pipeline-job')

# Update the pipeline script
update_pipeline_script(job, 'Jenkinsfile.build')

# Trigger the job
job.invoke()

List All Jobs

def list_all_jobs(jenkins):
    """List all Jenkins jobs with their status"""
    jobs = jenkins.get_jobs()
    for job_name, job_instance in jobs:
        last_build = job_instance.get_last_build_or_none()
        status = last_build.get_status() if last_build else "Never built"
        print(f"Job: {job_name}, Status: {status}")

list_all_jobs(jenkins)

Trigger Job with Parameters

def trigger_parameterized_job(jenkins, job_name, params):
    """Trigger a Jenkins job with parameters"""
    job = jenkins.get_job(job_name)

    # Trigger build with parameters
    queue_item = job.invoke(build_params=params)

    # Wait for build to start
    queue_item.block_until_building()
    build = queue_item.get_build()

    print(f"Build #{build.get_number()} started")

    # Optionally wait for completion
    build.block_until_complete()
    print(f"Build finished with status: {build.get_status()}")

    return build

# Example usage
params = {
    'BRANCH': 'main',
    'ENVIRONMENT': 'staging',
    'RUN_TESTS': True
}
build = trigger_parameterized_job(jenkins, 'deploy-app', params)

Get Build Console Output

def get_build_logs(jenkins, job_name, build_number=None):
    """Retrieve console output from a build"""
    job = jenkins.get_job(job_name)

    if build_number is None:
        build = job.get_last_build()
    else:
        build = job.get_build(build_number)

    console_output = build.get_console()
    print(console_output)
    return console_output

get_build_logs(jenkins, 'my-pipeline-job')

Copy Job Configuration

def clone_job(jenkins, source_job_name, new_job_name):
    """Clone an existing job with a new name"""
    source_job = jenkins.get_job(source_job_name)
    config_xml = source_job.get_config()

    # Create new job with the same configuration
    jenkins.create_job(new_job_name, config_xml)
    print(f"Created new job: {new_job_name}")

clone_job(jenkins, 'template-pipeline', 'new-project-pipeline')

Environment Variables

Store sensitive credentials as environment variables:

export JENKINS_URL="https://jenkins.example.com"
export JENKINS_USER="your-username"
export JENKINS_API_TOKEN="your-api-token"

Generate API token from Jenkins:

1. Navigate to your Jenkins user settings
2. Click “Configure”
3. Under “API Token”, click “Add new Token”
4. Copy and save the generated token