JenkinsAPI

Warnings

• breaking Jenkins versions 1.518 and above require disabling 'Prevent Cross Site Request Forgery exploits' in Jenkins' global security configuration for `jenkinsapi` to function correctly without additional configuration for CSRF tokens.
  Fix: Navigate to 'Manage Jenkins' > 'Configure Global Security' and uncheck 'Prevent Cross Site Request Forgery exploits'. For more secure setups, consider proxying requests or implementing a custom CSRF handling mechanism.
• gotcha The 'Jenkins Location' in Jenkins' global settings must be correctly configured, otherwise the REST API (which `jenkinsapi` uses) may not work as expected.
  Fix: In Jenkins, go to 'Manage Jenkins' > 'Configure System' and ensure 'Jenkins Location' (Jenkins URL) is set to the correct publicly accessible URL of your Jenkins instance.
• gotcha For Jenkins versions 1.426 and above, it is strongly recommended to use a Jenkins API token for authentication instead of a user's literal password. Using passwords directly is less secure.
  Fix: Generate an API token for your user in Jenkins (User > Configure > API Token) and use this token as the `password` argument when initializing the `Jenkins` object.
• gotcha When connecting to a Jenkins instance with a very large number of jobs, `jenkinsapi` might attempt to eagerly load information for all jobs, which can lead to long delays or timeouts. This behavior may cause scripts to hang or run out of memory.
  Fix: While `jenkinsapi` itself doesn't offer a 'lazy' loading option at the top level for all objects, be mindful of operations that iterate over `server.jobs` or similar collections. Consider fetching specific jobs or using filters if available, or exploring alternative Jenkins Python clients (like `python-jenkins` or `api4jenkins`) if this becomes a persistent performance bottleneck.
• gotcha Reliably tracking build queue items and their execution status can be challenging on highly active Jenkins servers. Queue items might be deleted between API calls, potentially leading to incorrect build status mappings or missed build events.
  Fix: Implement robust retry mechanisms and careful state tracking when interacting with the build queue. Be aware of potential race conditions and consider using Jenkins' built-in mechanisms for build notifications or webhooks if available and suitable for your use case, or poll build status with appropriate delays and error handling.

Install

• pip install jenkinsapi Install stable version

Imports

• Jenkins

  from jenkinsapi.jenkins import Jenkins

  This is the primary class for connecting to a Jenkins server.

Quickstart

This quickstart demonstrates how to connect to a Jenkins server using the `Jenkins` class and retrieve basic information like the server version and the count of configured jobs. It uses environment variables for Jenkins URL, username, and API token for secure credential management.

import os
from jenkinsapi.jenkins import Jenkins

JENKINS_URL = os.environ.get('JENKINS_URL', 'http://localhost:8080')
JENKINS_USERNAME = os.environ.get('JENKINS_USERNAME', 'admin') # Or 'JENKINS_USER'
JENKINS_API_TOKEN = os.environ.get('JENKINS_API_TOKEN', 'your_api_token_here') # Use an API token, not a user's password

def connect_to_jenkins():
    try:
        # It's highly recommended to use an API token for authentication,
        # which can be generated from your Jenkins user configuration page.
        server = Jenkins(JENKINS_URL, username=JENKINS_USERNAME, password=JENKINS_API_TOKEN)
        print(f"Successfully connected to Jenkins at {JENKINS_URL}. Jenkins version: {server.version}")
        
        # Example: Get the number of jobs
        print(f"Number of jobs configured: {len(server.jobs)}")

        # Example: List names of first 5 jobs
        # print("First 5 job names:")
        # for i, job_name in enumerate(server.jobs.keys()):
        #     if i >= 5:
        #         break
        #     print(f"  - {job_name}")

    except Exception as e:
        print(f"Failed to connect to Jenkins or retrieve information: {e}")
        print("Ensure JENKINS_URL, JENKINS_USERNAME, and JENKINS_API_TOKEN environment variables are set correctly.")

if __name__ == '__main__':
    connect_to_jenkins()