Clone or download
Latest commit 6e9a11f Nov 16, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib Added build.term Nov 15, 2018
test Added build.term Nov 15, 2018
.gitignore Add test information Aug 10, 2018
.jscs.json Convert to rapi Jul 14, 2014
.jshintrc Update jshint Feb 24, 2015
.npmignore Fix tests Aug 7, 2016
.travis.yml Update to latest dependencies Jun 10, 2018
LICENSE Implement node calls Jan 11, 2014
NOTES Tweak and expand notes regarding python-jenkins Sep 22, 2012
README.md Added build.term Nov 15, 2018
package.json Version 0.23.0 Nov 16, 2018

README.md

Jenkins Build Status

This is a Node.js client for Jenkins.

Documentation

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

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.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.job.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.