Jenkins

This is a Node.js client for Jenkins.

Documentation

jenkins: init, info
build: get, log, logStream, stop, term
job: build, get config, set config, copy, create, destroy, disable, enable, exists, get, list
label: get
node: get config, create, destroy, disconnect, disable, enable, exists, get, list
plugin: list
queue: list, item, cancel
view: get config, set config, create, destroy, exists, get, list, add job, remove job

Promise

Promise support can be enabled by setting promisify to true in Node >= 0.12 or passing a wrapper (ex: bluebird.fromCallback) in older versions.

Common Options

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)

jenkins([options])

Initialize a new Jenkins client.

Options

baseUrl (String): Jenkins URL
crumbIssuer (Boolean, default: false): enable CSRF Protection support
formData (Function, optional): enable file upload support on parameterized builds (must pass in require('form-data') as value for this option)
headers (Object, optional): headers included in every request
promisify (Boolean|Function, optional): convert callback methods to promises
and more via papi

Usage

var jenkins = require('jenkins')({ baseUrl: 'http://user:pass@localhost:8080', crumbIssuer: true });

jenkins.info(callback)

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/"
    }
  ]
}

jenkins.build.get(options, callback)

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/"
}

jenkins.build.log(options, callback)

Get build log.

Options

name (String): job name
number (Integer): build number
start (Integer, optional): start offset
type (String, enum: text, html, default: text): output format
meta (Boolean, default: false): return object with text (log data), more (boolean if there is more log data), and size (used with start to offset on subsequent calls)

Usage

jenkins.build.log('example', 1, function(err, data) {
  if (err) throw err;

  console.log('log', data);
});

jenkins.build.logStream(options, callback)

Get build log stream.

Options

name (String): job name
number (Integer): build number
type (String, enum: text, html, default: text): output format
delay (Integer, default: 1000): poll interval in milliseconds

Usage

var log = jenkins.build.logStream('example', 1);

log.on('data', function(text) {
  process.stdout.write(text);
});

log.on('error', function(err) {
  console.log('error', err);
});

log.on('end', function() {
  console.log('end');
});

jenkins.build.stop(options, callback)

Stop build.

Options

name (String): job name
number (Integer): build number

Usage

jenkins.build.stop('example', 1, function(err) {
  if (err) throw err;
});

jenkins.build.term(options, callback)

Terminates build.

Options

name (String): job name
number (Integer): build number

Usage

jenkins.build.term('example', 1, function(err) {
  if (err) throw err;
});

jenkins.job.build(options, callback)

Trigger build.

Options

name (String): job name
parameters (Object, optional): build parameters
token (String, optional): authorization token

Usage

jenkins.job.build('example', function(err, data) {
  if (err) throw err;

  console.log('queue item number', data);
});

jenkins.job.build({ name: 'example', parameters: { name: 'value' } }, function(err) {
  if (err) throw err;
});

jenkins.job.build({ name: 'example', parameters: { file: fs.createReadStream('test.txt') } }, function(err) {
  if (err) throw err;
});

jenkins.job.config(options, callback)

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);
});

jenkins.job.config(options, callback)

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;
});

jenkins.job.copy(options, callback)

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;
});

jenkins.job.create(options, callback)

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;
});

jenkins.job.destroy(options, callback)

Delete job.

Options

name (String): job name

Usage

jenkins.job.destroy('example', function(err) {
  if (err) throw err;
});

jenkins.job.disable(options, callback)

Disable job.

Options

name (String): job name

Usage

jenkins.job.disable('example', function(err) {
  if (err) throw err;
});

jenkins.job.enable(options, callback)

Enable job.

Options

name (String): job name

Usage

jenkins.job.enable('example', function(err) {
  if (err) throw err;
});

jenkins.job.exists(options, callback)

Check job exists.

Options

name (String): job name

Usage

jenkins.job.exists('example', function(err, exists) {
  if (err) throw err;

  console.log('exists', exists);
});

jenkins.job.get(options, callback)

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/"
}

jenkins.job.list(callback)

List jobs.

Options

name (String, optional): folder name

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/"
  }
]

jenkins.label.get(options, callback)

Get label information.

Options

name (String): label name

Usage

jenkins.label.get('master', function(err, data) {
  if (err) throw err;

  console.log('label', data);
});

Result

{
  "_class": "hudson.model.labels.LabelAtom",
  "actions": [],
  "busyExecutors": 0,
  "clouds": [],
  "description": null,
  "idleExecutors": 2,
  "loadStatistics": {
    "_class": "hudson.model.Label$1"
  },
  "name": "master",
  "nodes": [
    {
      "_class": "hudson.model.Hudson",
      "nodeName": ""
    }
  ],
  "offline": false,
  "tiedJobs": [],
  "totalExecutors": 2,
  "propertiesList": []
}

jenkins.node.config(options, callback)

Get node XML configuration.

Options

name (String): node name

Usage

jenkins.node.config('example', function(err, data) {
  if (err) throw err;

  console.log('xml', data);
});

jenkins.node.create(options, callback)

Create node.

Options

name (String): node name

Usage

jenkins.node.create('slave', function(err) {
  if (err) throw err;
});

jenkins.node.destroy(options, callback)

Delete node.

Options

name (String): node name

Usage

jenkins.node.destroy('slave', function(err) {
  if (err) throw err;
});

jenkins.node.disconnect(options, callback)

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;
});

jenkins.node.disable(options, callback)

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;
});

jenkins.node.enable(options, callback)

Enable node.

Options

name (String): node name

Usage

jenkins.node.enable('slave', function(err) {
  if (err) throw err;
});

jenkins.node.exists(options, callback)

Check node exists.

Options

name (String): node name

Usage

jenkins.node.exists('slave', function(err, exists) {
  if (err) throw err;

  console.log('exists', exists);
});

jenkins.node.get(options, callback)

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
}

jenkins.node.list(callback)

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
}

jenkins.plugin.list(callback)

List plugins (note: depth defaults to 1).

Usage

jenkins.plugin.list(function(err, data) {
  if (err) throw err;

  console.log('plugins', data);
});

Result

[{
  "active": true,
  "backupVersion": null,
  "bundled": false,
  "deleted": false,
  "dependencies": [
    {},
    {},
    {},
    {},
    {},
    {},
    {},
    {}
  ],
  "downgradable": false,
  "enabled": true,
  "hasUpdate": false,
  "longName": "Email Extension Plugin",
  "pinned": false,
  "shortName": "email-ext",
  "supportsDynamicLoad": "MAYBE",
  "url": "http://wiki.jenkins-ci.org/display/JENKINS/Email-ext plugin",
  "version": "2.53"
}]

jenkins.queue.list(callback)

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)"
    }
  ]
}

jenkins.queue.item(options, callback)

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/"
  }
}

jenkins.queue.cancel(options, callback)

Cancel build in queue.

Options

number (Integer): queue item id

Usage

jenkins.queue.cancel(23, function(err) {
  if (err) throw err;
});

jenkins.view.config(options, callback)

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);
});

jenkins.view.config(options, callback)

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;
});

jenkins.view.create(options, callback)

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;
});

jenkins.view.destroy(options, callback)

Delete view.

Options

name (String): view name

Usage

jenkins.view.destroy('example', function(err) {
  if (err) throw err;
});

jenkins.view.exists(options, callback)

Check view exists.

Options

name (String): view name

Usage

jenkins.view.exists('example', function(err, exists) {
  if (err) throw err;

  console.log('exists', exists);
});

jenkins.view.get(options, callback)

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/"
}

jenkins.view.list(callback)

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": {}
}

jenkins.view.add(options, callback)

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;
});

jenkins.view.remove(options, callback)

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;
});

Test

Run unit tests

$ npm test

Run acceptance tests

$ docker-compose -f test/docker-compose.yml up -d
$ npm run acceptance
$ docker-compose -f test/docker-compose.yml down

License

This work is licensed under the MIT License (see the LICENSE file).

Notes

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.

Name		Name	Last commit message	Last commit date
Latest commit History 166 Commits
.github/workflows		.github/workflows
lib		lib
test		test
.gitignore		.gitignore
.jscs.json		.jscs.json
.jshintrc		.jshintrc
.npmignore		.npmignore
LICENSE		LICENSE
NOTES		NOTES
README.md		README.md
package.json		package.json

License

fczj/node-jenkins

Folders and files

Latest commit

History

Repository files navigation

Jenkins

Documentation

Promise

Common Options

jenkins([options])

jenkins.info(callback)

jenkins.build.get(options, callback)

jenkins.build.log(options, callback)

jenkins.build.logStream(options, callback)

jenkins.build.stop(options, callback)

jenkins.build.term(options, callback)

jenkins.job.build(options, callback)

jenkins.job.config(options, callback)

jenkins.job.config(options, callback)

jenkins.job.copy(options, callback)

jenkins.job.create(options, callback)

jenkins.job.destroy(options, callback)

jenkins.job.disable(options, callback)

jenkins.job.enable(options, callback)

jenkins.job.exists(options, callback)

jenkins.job.get(options, callback)

jenkins.job.list(callback)

jenkins.label.get(options, callback)

jenkins.node.config(options, callback)

jenkins.node.create(options, callback)

jenkins.node.destroy(options, callback)

jenkins.node.disconnect(options, callback)

jenkins.node.disable(options, callback)

jenkins.node.enable(options, callback)

jenkins.node.exists(options, callback)

jenkins.node.get(options, callback)

jenkins.node.list(callback)

jenkins.plugin.list(callback)

jenkins.queue.list(callback)

jenkins.queue.item(options, callback)

jenkins.queue.cancel(options, callback)

jenkins.view.config(options, callback)

jenkins.view.config(options, callback)

jenkins.view.create(options, callback)

jenkins.view.destroy(options, callback)

jenkins.view.exists(options, callback)

jenkins.view.get(options, callback)

jenkins.view.list(callback)

jenkins.view.add(options, callback)

jenkins.view.remove(options, callback)

Test

License

Notes

About

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Languages

Packages