[!CAUTION] This project is no longer maintained.

Jenkins

This is a Node.js client for Jenkins.

Documentation

• jenkins: init, info
• build: get, artifact, artifactsZip, log, logStream, stop, term
• credentials: create, exists, get config, set config, destroy, list
• job: build, get config, set config, copy, create, create folder, 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",
});

TypeScript

The package now includes bundled type definitions. Import the client as usual and enjoy autocomplete and compile-time checks.

import Jenkins from "jenkins";

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

async function main() {
  await jenkins.job.build("example", { waitForBuild: true });
}

void main();

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): Jenkins endpoint variant to call
• format (String, enum: text, json, default: text): response shape (json requires type !== "html")
• 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). This is always enabled when format is json.

When requesting JSON logs, each entry in lines includes the human-readable message along with a step property for Jenkins Pipeline flow markers (for example, Start of Pipeline), plus a raw field containing the original text with any hidden metadata intact.

Usage

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

const data = await jenkins.build.log("example", 1, { format: "json" });

console.log(data.lines);
// [ { line: 0, message: "Started by user admin" }, ... ]

jenkins.build.logStream(options)

Get build log stream.

Options

• name (String): job name
• number (Integer): build number
• type (String, enum: text, html, default: text): Jenkins endpoint variant to call
• format (String, enum: text, json, default: text): response shape for emitted data events
• 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");
});

const jsonLog = jenkins.build.logStream("example", 1, {
  format: "json",
});

jsonLog.on("data", (entry) => {
  console.log(entry.line, entry.message, entry.step);
});

The JSON stream emits the same enriched objects as jenkins.build.log, so entry.step contains Jenkins Pipeline markers (when present) and entry.raw preserves the original log text.

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.build.artifact(options)

Download a single artifact from a build.

Options

• name (String): job name
• number (Integer): build number
• path (String): relative artifact path, as shown in the Jenkins UI
• accept (String, optional): override the Accept header sent to Jenkins

Usage

const data = await jenkins.build.artifact("example", 1, "dist/app.zip");

console.log(`Downloaded ${data.length} bytes`);

jenkins.build.artifactsZip(options)

Download all artifacts from a build as a single zip archive.

Options

• name (String): job name
• number (Integer): build number
• filename (String, optional): filename Jenkins should use for the archive (defaults to archive.zip)
• accept (String, optional): override the Accept header sent to Jenkins

Usage

const archive = await jenkins.build.artifactsZip("example", 1);

console.log(`Downloaded archive with ${archive.length} bytes`);

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 (resolves to the started build number by default).

Options

• name (String): job name
• parameters (Object, optional): build parameters
• token (String, optional): authorization token
• waitForBuild (Boolean, default: true): resolve with the started build number; set to false to return the queue id immediately
• buildNumberTimeout (Number, optional): max time in milliseconds to wait for the build to start (defaults to five minutes)
• buildNumberPollInterval (Number, optional): polling interval in milliseconds while waiting for the build to start (defaults to one second)

Usage

const buildNumber = await jenkins.job.build("example");

const queueId = await jenkins.job.build({
  name: "example",
  parameters: { name: "value" },
  waitForBuild: false,
});

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
• autoToggle (Boolean, optional, default: true): automatically disable then re-enable the copied job once Jenkins reports it exists
• toggleTimeout (Number, optional, default: 30000): how long to wait (in milliseconds) for the new job to appear before toggling
• togglePollInterval (Number, optional, default: 500): polling interval (in milliseconds) used while waiting for the job

Usage

const summary = await jenkins.job.copy("fromJob", "example", {
  toggleTimeout: 60000,
});

// summary -> {
//   name: "example",
//   from: "fromJob",
//   copied: true,
//   ready: true,
//   disabled: true,
//   enabled: true,
//   toggled: true,
//   autoToggle: true,
//   message: "Copy completed and job toggled",
//   rawResponse: undefined
// }

// Skip the post-copy disable/enable cycle if you don't need it
await jenkins.job.copy("fromJob", "example", { autoToggle: false });

// You can also provide a single options object, which is helpful when
// working with nested folders:
await jenkins.job.copy({
  from: "legacy-folder/pipeline-A",
  name: "team/mobile/pipeline-A",
  toggleTimeout: 45000,
});

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.createFolder(options)

Create a folder via the CloudBees Folder plugin.

Options

• name (String): folder path (for example team/mobile)
• mode (String, optional): Jenkins mode parameter (defaults to com.cloudbees.hudson.plugins.folder.Folder)
• from (String, optional): source item name when copying (defaults to empty)
• displayName (String, optional): display name shown in the Jenkins UI
• description (String, optional): description text stored with the folder
• skipExistsCheck (Boolean, optional): set to true to skip the pre-flight existence check (defaults to false)

Usage

const summary = await jenkins.job.createFolder("team/mobile", {
  displayName: "Mobile Team",
});

// summary -> {
//   "Folder:Name": "team/mobile",
//   Created: true,
//   message: "Folder team/mobile created successfully",
//   exists: true
// }

If the folder already exists the call resolves with the same structure, but
`Created` is `false` and `message` describes the conflict instead of throwing
an error. This detection requires an extra `HEAD` request; pass
`skipExistsCheck: true` if you prefer to skip that check.

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.