This is a Node.js client for Jenkins.
- jenkins: init, info
- build: get, log, stop
- job: build, get config, set config, copy, create, destroy, disable, enable, exists, get, list
- node: create, destroy, disconnect, disable, enable, exists, get, list
- queue: list, cancel
- view: get config, set config, create, destroy, exists, get, list, add job, remove job
Promise support can be enabled by setting promisify
to true
in Node >= 0.12
or passing a wrapper (ex: bluebird.fromCallback
) in older versions.
These options will be passed along with any call, although only certain endpoints support them.
- depth (Number, default: 0): how much data to return (see depth control)
- tree (String, optional): path expression (see Jenkins API documentation for more information)
Initialize a new Jenkins client.
Options
- baseUrl (String): Jenkins URL
- headers (Object, optional): headers included in every request
- promisify (Boolean|Function, optional): convert callback methods to promises
Usage
var jenkins = require('jenkins')('http://user:pass@localhost:8080');
Get server information.
Usage
jenkins.info(function(err, data) {
if (err) throw err;
console.log('info', data);
});
Result
{
"assignedLabels": [
{}
],
"description": null,
"jobs": [
{
"color": "blue",
"name": "example",
"url": "http://localhost:8080/job/example/"
}
],
"mode": "NORMAL",
"nodeDescription": "the master Jenkins node",
"nodeName": "",
"numExecutors": 2,
"overallLoad": {},
"primaryView": {
"name": "All",
"url": "http://localhost:8080/"
},
"quietingDown": false,
"slaveAgentPort": 12345,
"unlabeledLoad": {},
"useCrumbs": false,
"useSecurity": false,
"views": [
{
"name": "All",
"url": "http://localhost:8080/"
}
]
}
Get build information.
Options
- name (String): job name
- number (Integer): build number
Usage
jenkins.build.get('example', 1, function(err, data) {
if (err) throw err;
console.log('build', data);
});
Result
{
"actions": [],
"buildable": true,
"builds": [
{
"number": 1,
"url": "http://localhost:8080/job/example/1/"
}
],
"color": "blue",
"concurrentBuild": false,
"description": "",
"displayName": "example",
"displayNameOrNull": null,
"downstreamProjects": [],
"firstBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"healthReport": [
{
"description": "Build stability: No recent builds failed.",
"iconUrl": "health-80plus.png",
"score": 100
}
],
"inQueue": false,
"keepDependencies": false,
"lastBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastCompletedBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastFailedBuild": null,
"lastStableBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastSuccessfulBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastUnstableBuild": null,
"lastUnsuccessfulBuild": null,
"name": "example",
"nextBuildNumber": 2,
"property": [],
"queueItem": null,
"scm": {},
"upstreamProjects": [],
"url": "http://localhost:8080/job/example/"
}
Get build log.
Options
- name (String): job name
- number (Integer): build number
Usage
jenkins.build.log('example', 1, function(err, data) {
if (err) throw err;
console.log('buildLog', data);
});
Stop build.
Options
- name (String): job name
- number (Integer): build number
Usage
jenkins.build.stop('example', 1, function(err) {
if (err) throw err;
});
Trigger build.
Options
- name (String): job name
- parameters (Object, optional): build parameters
- token (String, optional): authorization token
Usage
jenkins.job.build('example', function(err) {
if (err) throw err;
});
Get job XML configuration.
Options
- name (String): job name
Usage
jenkins.job.config('example', function(err, data) {
if (err) throw err;
console.log('xml', data);
});
Update job XML configuration.
Options
- name (String): job name
- xml (String): configuration XML
Usage
jenkins.job.config('example', xml, function(err) {
if (err) throw err;
});
Create job by copying existing job.
Options
- name (String): new job name
- from (String): source job name
Usage
jenkins.job.copy('fromJob', 'example', function(err) {
if (err) throw err;
});
Create job from scratch.
Options
- name (String): job name
- xml (String): configuration XML
Usage
jenkins.job.create('example', xml, function(err) {
if (err) throw err;
});
Delete job.
Options
- name (String): job name
Usage
jenkins.job.destroy('example', function(err) {
if (err) throw err;
});
Disable job.
Options
- name (String): job name
Usage
jenkins.job.disable('example', function(err) {
if (err) throw err;
});
Enable job.
Options
- name (String): job name
Usage
jenkins.job.enable('example', function(err) {
if (err) throw err;
});
Check job exists.
Options
- name (String): job name
Usage
jenkins.job.exists('example', function(err, exists) {
if (err) throw err;
console.log('exists', exists);
});
Get job information.
Options
- name (String): job name
Usage
jenkins.job.get('example', function(err, data) {
if (err) throw err;
console.log('job', data);
});
Result
{
"actions": [],
"buildable": true,
"builds": [
{
"number": 1,
"url": "http://localhost:8080/job/example/1/"
}
],
"color": "blue",
"concurrentBuild": false,
"description": "",
"displayName": "example",
"displayNameOrNull": null,
"downstreamProjects": [],
"firstBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"healthReport": [
{
"description": "Build stability: No recent builds failed.",
"iconUrl": "health-80plus.png",
"score": 100
}
],
"inQueue": false,
"keepDependencies": false,
"lastBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastCompletedBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastFailedBuild": null,
"lastStableBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastSuccessfulBuild": {
"number": 1,
"url": "http://localhost:8080/job/example/1/"
},
"lastUnstableBuild": null,
"lastUnsuccessfulBuild": null,
"name": "example",
"nextBuildNumber": 2,
"property": [],
"queueItem": null,
"scm": {},
"upstreamProjects": [],
"url": "http://localhost:8080/job/example/"
}
List all jobs.
Usage
jenkins.job.list(function(err, data) {
if (err) throw err;
console.log('jobs', data);
});
Result
[
{
"color": "blue",
"name": "example",
"url": "http://localhost:8080/job/example/"
}
]
Create node.
Options
- name (String): node name
Usage
jenkins.node.create('slave', function(err) {
if (err) throw err;
});
Delete node.
Options
- name (String): node name
Usage
jenkins.node.destroy('slave', function(err) {
if (err) throw err;
});
Disconnect node.
Options
- name (String): node name
- message (String, optional): reason for being disconnected
Usage
jenkins.node.disconnect('slave', 'no longer used', function(err) {
if (err) throw err;
});
Disable node.
Options
- name (String): node name
- message (String, optional): reason for being disabled
Usage
jenkins.node.disable('slave', 'network failure', function(err) {
if (err) throw err;
});
Enable node.
Options
- name (String): node name
Usage
jenkins.node.enable('slave', function(err) {
if (err) throw err;
});
Check node exists.
Options
- name (String): node name
Usage
jenkins.node.exists('slave', function(err, exists) {
if (err) throw err;
console.log('exists', exists);
});
Get node information.
Options
- name (String): node name
Usage
jenkins.node.get('slave', function(err, data) {
if (err) throw err;
console.log('node', data);
});
Result
{
"actions": [],
"displayName": "slave",
"executors": [
{},
{}
],
"icon": "computer-x.png",
"idle": true,
"jnlpAgent": true,
"launchSupported": false,
"loadStatistics": {},
"manualLaunchAllowed": true,
"monitorData": {
"hudson.node_monitors.ArchitectureMonitor": null,
"hudson.node_monitors.ClockMonitor": null,
"hudson.node_monitors.DiskSpaceMonitor": null,
"hudson.node_monitors.ResponseTimeMonitor": {
"average": 5000
},
"hudson.node_monitors.SwapSpaceMonitor": null,
"hudson.node_monitors.TemporarySpaceMonitor": null
},
"numExecutors": 2,
"offline": true,
"offlineCause": null,
"offlineCauseReason": "",
"oneOffExecutors": [],
"temporarilyOffline": false
}
List all nodes.
Options
- full (Boolean, default: false): include executor count in response
Usage
jenkins.node.list(function(err, data) {
if (err) throw err;
console.log('nodes', data);
});
Result
{
"busyExecutors": 0,
"computer": [
{
"actions": [],
"displayName": "master",
"executors": [
{},
{}
],
"icon": "computer.png",
"idle": true,
"jnlpAgent": false,
"launchSupported": true,
"loadStatistics": {},
"manualLaunchAllowed": true,
"monitorData": {
"hudson.node_monitors.ArchitectureMonitor": "Linux (amd64)",
"hudson.node_monitors.ClockMonitor": {
"diff": 0
},
"hudson.node_monitors.DiskSpaceMonitor": {
"path": "/var/lib/jenkins",
"size": 77620142080
},
"hudson.node_monitors.ResponseTimeMonitor": {
"average": 0
},
"hudson.node_monitors.SwapSpaceMonitor": {
"availablePhysicalMemory": 22761472,
"availableSwapSpace": 794497024,
"totalPhysicalMemory": 515358720,
"totalSwapSpace": 805302272
},
"hudson.node_monitors.TemporarySpaceMonitor": {
"path": "/tmp",
"size": 77620142080
}
},
"numExecutors": 2,
"offline": false,
"offlineCause": null,
"offlineCauseReason": "",
"oneOffExecutors": [],
"temporarilyOffline": false
},
{
"actions": [],
"displayName": "slave",
"executors": [
{},
{}
],
"icon": "computer-x.png",
"idle": true,
"jnlpAgent": true,
"launchSupported": false,
"loadStatistics": {},
"manualLaunchAllowed": true,
"monitorData": {
"hudson.node_monitors.ArchitectureMonitor": null,
"hudson.node_monitors.ClockMonitor": null,
"hudson.node_monitors.DiskSpaceMonitor": null,
"hudson.node_monitors.ResponseTimeMonitor": {
"average": 5000
},
"hudson.node_monitors.SwapSpaceMonitor": null,
"hudson.node_monitors.TemporarySpaceMonitor": null
},
"numExecutors": 2,
"offline": true,
"offlineCause": null,
"offlineCauseReason": "",
"oneOffExecutors": [],
"temporarilyOffline": false
}
],
"displayName": "nodes",
"totalExecutors": 2
}
List queues.
Usage
jenkins.queue.list(function(err, data) {
if (err) throw err;
console.log('queues', data);
});
Result
{
"items": [
{
"actions": [
{
"causes": [
{
"shortDescription": "Started by user anonymous",
"userId": null,
"userName": "anonymous"
}
]
}
],
"blocked": true,
"buildable": false,
"buildableStartMilliseconds": 1389418977387,
"id": 20,
"inQueueSince": 1389418977358,
"params": "",
"stuck": false,
"task": {
"color": "blue_anime",
"name": "example",
"url": "http://localhost:8080/job/example/"
},
"url": "queue/item/20/",
"why": "Build #2 is already in progress (ETA:N/A)"
}
]
}
Lookup a queue item.
Options
- number (Integer): queue item number
Usage
jenkins.queue.item(130, function(err, data) {
if (err) throw err;
console.log('item', data);
});
Result
{
"actions": [
{
"causes": [
{
"shortDescription": "Started by user anonymous",
"userId": null,
"userName": "anonymous"
}
]
}
],
"blocked": false,
"buildable": false,
"id": 130,
"inQueueSince": 1406363479853,
"params": "",
"stuck": false,
"task": {
"name": "test-job-b7ef0845-6515-444c-96a1-d2266d5e0f18",
"url": "http://localhost:8080/job/test-job-b7ef0845-6515-444c-96a1-d2266d5e0f18/",
"color": "blue"
},
"url": "queue/item/130/",
"why": null,
"executable" : {
"number" : 28,
"url" : "http://localhost:8080/job/test-job-b7ef0845-6515-444c-96a1-d2266d5e0f18/28/"
}
}
Cancel build in queue.
Options
- number (Integer): queue item id
Usage
jenkins.queue.cancel(23, function(err) {
if (err) throw err;
});
Get view XML configuration.
Options
- name (String): job name
Usage
jenkins.view.config('example', function(err, data) {
if (err) throw err;
console.log('xml', data);
});
Update view XML configuration.
Options
- name (String): job name
- xml (String): configuration XML
Usage
jenkins.view.config('example', xml, function(err) {
if (err) throw err;
});
Create view.
Options
- name (String): view name
- type (String, enum: list, my): view type
Usage
jenkins.view.create('example', 'list', function(err) {
if (err) throw err;
});
Delete view.
Options
- name (String): view name
Usage
jenkins.view.destroy('example', function(err) {
if (err) throw err;
});
Check view exists.
Options
- name (String): view name
Usage
jenkins.view.exists('example', function(err, exists) {
if (err) throw err;
console.log('exists', exists);
});
Get view information.
Options
- name (String): view name
Usage
jenkins.view.get('example', function(err, data) {
if (err) throw err;
console.log('view', data);
});
Result
{
"description": null,
"jobs": [
{
"name": "test",
"url": "http://localhost:8080/job/example/",
"color": "blue"
}
],
"name": "example",
"property": [],
"url": "http://localhost:8080/view/example/"
}
List all views.
Usage
jenkins.view.list(function(err, data) {
if (err) throw err;
console.log('views', data);
});
Result
{
"views": [
{
"url": "http://localhost:8080/",
"name": "All"
},
{
"url": "http://localhost:8080/view/example/",
"name": "Test"
}
],
"useSecurity": false,
"useCrumbs": false,
"unlabeledLoad": {},
"slaveAgentPort": 0,
"quietingDown": false,
"primaryView": {
"url": "http://localhost:8080/",
"name": "All"
},
"assignedLabels": [
{}
],
"mode": "NORMAL",
"nodeDescription": "the master Jenkins node",
"nodeName": "",
"numExecutors": 2,
"description": null,
"jobs": [
{
"color": "notbuilt",
"url": "http://localhost:8080/job/example/",
"name": "test"
}
],
"overallLoad": {}
}
Add job to view.
Options
- name (String): view name
- job (String): job name
Usage
jenkins.view.add('example', 'jobExample', function(err) {
if (err) throw err;
});
Remove job from view.
Options
- name (String): view name
- job (String): job name
Usage
jenkins.view.remove('example', 'jobExample', function(err) {
if (err) throw err;
});
This work is licensed under the MIT License (see the LICENSE file).
python-jenkins (BSD License, see NOTES) was used as a reference when implementing this client and its create/reconfigure job XML was used in the tests.