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,