{"id":4365,"library":"jenkinsapi","title":"JenkinsAPI","description":"JenkinsAPI is a Python library that provides an object-oriented interface for interacting with a Jenkins continuous integration server. It wraps the Jenkins REST API, making it easier to query the server's state, manage jobs, builds, nodes, and artifacts, and automate various Jenkins tasks. The library is actively maintained, with regular updates addressing bug fixes and new features, and is currently at version 0.3.22.","status":"active","version":"0.3.22","language":"en","source_language":"en","source_url":"https://github.com/pycontribs/jenkinsapi","tags":["jenkins","ci","cd","automation","api","continuous-integration"],"install":[{"cmd":"pip install jenkinsapi","lang":"bash","label":"Install stable version"}],"dependencies":[],"imports":[{"note":"This is the primary class for connecting to a Jenkins server.","symbol":"Jenkins","correct":"from jenkinsapi.jenkins import Jenkins"}],"quickstart":{"code":"import os\nfrom jenkinsapi.jenkins import Jenkins\n\nJENKINS_URL = os.environ.get('JENKINS_URL', 'http://localhost:8080')\nJENKINS_USERNAME = os.environ.get('JENKINS_USERNAME', 'admin') # Or 'JENKINS_USER'\nJENKINS_API_TOKEN = os.environ.get('JENKINS_API_TOKEN', 'your_api_token_here') # Use an API token, not a user's password\n\ndef connect_to_jenkins():\n    try:\n        # It's highly recommended to use an API token for authentication,\n        # which can be generated from your Jenkins user configuration page.\n        server = Jenkins(JENKINS_URL, username=JENKINS_USERNAME, password=JENKINS_API_TOKEN)\n        print(f\"Successfully connected to Jenkins at {JENKINS_URL}. Jenkins version: {server.version}\")\n        \n        # Example: Get the number of jobs\n        print(f\"Number of jobs configured: {len(server.jobs)}\")\n\n        # Example: List names of first 5 jobs\n        # print(\"First 5 job names:\")\n        # for i, job_name in enumerate(server.jobs.keys()):\n        #     if i >= 5:\n        #         break\n        #     print(f\"  - {job_name}\")\n\n    except Exception as e:\n        print(f\"Failed to connect to Jenkins or retrieve information: {e}\")\n        print(\"Ensure JENKINS_URL, JENKINS_USERNAME, and JENKINS_API_TOKEN environment variables are set correctly.\")\n\nif __name__ == '__main__':\n    connect_to_jenkins()","lang":"python","description":"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."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"Jenkins >= 1.518"},{"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.","message":"The 'Jenkins Location' in Jenkins' global settings must be correctly configured, otherwise the REST API (which `jenkinsapi` uses) may not work as expected.","severity":"gotcha","affected_versions":"All Jenkins versions"},{"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.","message":"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.","severity":"gotcha","affected_versions":"Jenkins >= 1.426"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially with large Jenkins instances"},{"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.","message":"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.","severity":"gotcha","affected_versions":"All versions, especially under high load"}],"env_vars":null,"last_verified":"2026-04-12T00:00:00.000Z","next_check":"2026-07-11T00:00:00.000Z"}