jenkins
    DefinitelyTyped icon, indicating that this package has TypeScript declarations provided by the separate @types/jenkins package

    0.28.1 • Public • Published

    Jenkins

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

    Keywords

    Install

    npm i jenkins

    DownloadsWeekly Downloads

    11,480

    Version

    0.28.1

    License

    MIT

    Unpacked Size

    81.8 kB

    Total Files

    18

    Last publish

    Collaborators

    • silas