Jenkins NPM | npm.io

Jenkins

This is a Node.js client for Jenkins.

Documentation

jenkins: init, info
build: get, log, logStream, stop, term
credentials: create, exists, get config, set config, destroy, list
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

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: true): 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
and more via papi

Usage

import Jenkins from "jenkins";

const jenkins = new Jenkins({
  baseUrl: "http://user:pass@localhost:8080",
});

jenkins.info(callback)

Get server information.

Usage

await jenkins.info();

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)

Get build information.

Options

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

Usage

await jenkins.build.get("example", 1);

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)

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

await jenkins.build.log("example", 1);

jenkins.build.logStream(options)

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

const log = jenkins.build.logStream("example", 1);

log.on("data", (text) => {
  process.stdout.write(text);
});

log.on("error", (err) => {
  console.log("error", err);
});

log.on("end", () => {
  console.log("end");
});

jenkins.build.stop(options)

Stop build.

Options

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

Usage

await jenkins.build.stop("example", 1);

jenkins.build.term(options)

Terminates build.

Options

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

Usage

await jenkins.build.term("example", 1);

jenkins.credentials.create(options)

Create credentials in a folder or system.

Options

folder (String): path of the folder or manage for system credentials
store (String): the credentials store, can be either folder or system
domain (String): the credentials domain
xml (String): configuration XML

Usage

await jenkins.credentials.create("folder", "store", "domain", "xml");

jenkins.credentials.exists(options)

Check if credentials exist in a folder or system.

Options

id (String): the id of the credentials
folder (String): path of the folder or manage for system credentials
store (String): the credentials store, can be either folder or system
domain (String): the credentials domain

Usage

await jenkins.credentials.exists("id", "folder", "store", "domain");

jenkins.credentials.config(options)

Get XML configuration of credentials.

Options

id (String): the id of the credentials
folder (String): path of the folder or manage for system credentials
store (String): the credentials store, can be either folder or system
domain (String): the credentials domain

Usage

await jenkins.credentials.config("id", "folder", "store", "domain");

jenkins.credentials.config(options)

Update credentials.

Options

id (String): the id of the credential
folder (String): path of the folder or manage for system credentials
store (String): the credentials store, can be either folder or system
domain (String): the credentials domain
xml (String): configuration XML

Usage

await jenkins.credentials.update("id", "folder", "store", "domain", "xml");

jenkins.credentials.destroy(options)

Delete credentials from folder or system.

Options

id (String): the id of the credential
folder (String): path of the folder or manage for system credentials
store (String): the credentials store, can be either folder or system
domain (String): the credentials domain

Usage

await jenkins.credentials.destroy("id", "folder", "store", "domain");

jenkins.credentials.list(options)

Get a list of credentials in a folder or system.

Options

folder (String): path of the folder or manage for system credentials
store (String): the credentials store, can be either folder or system
domain (String): the credentials domain

Usage

await jenkins.credentials.list("folder", "store", "domain");

jenkins.job.build(options)

Trigger build.

Options

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

Usage

await jenkins.job.build("example");

await jenkins.job.build({
  name: "example",
  parameters: { name: "value" },
});

await jenkins.job.build({
  name: "example",
  parameters: { file: fs.createReadStream("test.txt") },
});

jenkins.job.config(options)

Get job XML configuration.

Options

name (String): job name

Usage

await jenkins.job.config("example");

jenkins.job.config(options)

Update job XML configuration.

Options

name (String): job name
xml (String): configuration XML

Usage

await jenkins.job.config("example", xml);

jenkins.job.copy(options)

Create job by copying existing job.

Options

name (String): new job name
from (String): source job name

Usage

await jenkins.job.copy("fromJob", "example");

jenkins.job.create(options)

Create job from scratch.

Options

name (String): job name
xml (String): configuration XML

Usage

await jenkins.job.create("example", xml);

jenkins.job.destroy(options)

Delete job.

Options

name (String): job name

Usage

await jenkins.job.destroy("example");

jenkins.job.disable(options)

Disable job.

Options

name (String): job name

Usage

await jenkins.job.disable("example");

jenkins.job.enable(options)

Enable job.

Options

name (String): job name

Usage

await jenkins.job.enable("example");

jenkins.job.exists(options)

Check job exists.

Options

name (String): job name

Usage

await jenkins.job.exists("example");

jenkins.job.get(options)

Get job information.

Options

name (String): job name

Usage

await jenkins.job.get("example");

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

await jenkins.job.list();

Result

[
  {
    "color": "blue",
    "name": "example",
    "url": "http://localhost:8080/job/example/"
  }
]

jenkins.label.get(options)

Get label information.

Options

name (String): label name

Usage

await jenkins.label.get("master");

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)

Get node XML configuration.

Options

name (String): node name

Usage

await jenkins.node.config("example");

jenkins.node.create(options)

Create node.

Options

name (String): node name

Usage

await jenkins.node.create("node-name");

jenkins.node.destroy(options)

Delete node.

Options

name (String): node name

Usage

await jenkins.node.destroy("node-name");

jenkins.node.disconnect(options)

Disconnect node.

Options

name (String): node name
message (String, optional): reason for being disconnected

Usage

await jenkins.node.disconnect("node-name", "no longer used");

jenkins.node.disable(options)

Disable node.

Options

name (String): node name
message (String, optional): reason for being disabled

Usage

await jenkins.node.disable("node-name", "network failure");

jenkins.node.enable(options)

Enable node.

Options

name (String): node name

Usage

await jenkins.node.enable("node-name");

jenkins.node.exists(options)

Check node exists.

Options

name (String): node name

Usage

await jenkins.node.exists("node-name");

jenkins.node.get(options)

Get node information.

Options

name (String): node name

Usage

await jenkins.node.get("node-name");

Result

{
  "actions": [],
  "displayName": "node-name",
  "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

await jenkins.node.list();

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": "node-name",
      "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

await jenkins.plugin.list();

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

await jenkins.queue.list();

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)

Lookup a queue item.

Options

number (Integer): queue item number

Usage

await jenkins.queue.item(130);

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)

Cancel build in queue.

Options

number (Integer): queue item id

Usage

await jenkins.queue.cancel(23);

jenkins.view.config(options)

Get view XML configuration.

Options

name (String): job name

Usage

await jenkins.view.config("example");

jenkins.view.config(options)

Update view XML configuration.

Options

name (String): job name
xml (String): configuration XML

Usage

await jenkins.view.config("example", xml);

jenkins.view.create(options)

Create view.

Options

name (String): view name
type (String, enum: list, my): view type

Usage

await jenkins.view.create("example", "list");

jenkins.view.destroy(options)

Delete view.

Options

name (String): view name

Usage

await jenkins.view.destroy("example");

jenkins.view.exists(options)

Check view exists.

Options

name (String): view name

Usage

await jenkins.view.exists("example");

jenkins.view.get(options)

Get view information.

Options

name (String): view name

Usage

await jenkins.view.get("example");

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

await jenkins.view.list();

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)

Add job to view.

Options

name (String): view name
job (String): job name

Usage

await jenkins.view.add("example", "jobExample");

jenkins.view.remove(options)

Remove job from view.

Options

name (String): view name
job (String): job name

Usage

await jenkins.view.remove("example", "jobExample");

Test

Run unit tests

$ npm test

Run acceptance tests

$ docker compose -f test/compose.yml up -d --build
$ npm run acceptance
$ docker compose -f test/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.

jenkins

papi