Jenkins Jobs Runner

This article is part of a Jenkins CLI series in which we describe how we built CLI application for executing a series of parallel Jenkins Jobs in a terminal.

Jenkins Jobs Runner is a library powered by Jenkins RxJs that enables sequential execution of n batches, each of m parallel jobs. On top of that, it provides a visual interface to display the current status of jobs.

How it works?

Jenkins Jobs Runner takes as an input array of JobBatchDescriptor object. They are expressed through an interface:

import { JobBuildOptions } from 'jenkins';
export interface JobBatchDescriptor<T1 = string, T2 = string> {
  displayName: T1;
  jobDescriptor: JobDescriptor<T2>[];
}
export interface JobDescriptor<T = string> {
  displayName: T;
  opts: JobBuildOptions;
}

Then, for each batch it follows this simple schema:

Await Execute Batch

This step goes as follows:

1. For each Job in Batch create Display Stream
2. UI Manager updates UI for every value emitted in the stream
3. Combine Display Streams of all Jobs in the Batch
4. Convert it to a Promise
5. Await completion of the Combined Streams

Display Stream

Display Stream is a combination of an original JobResponse stream from Jenkins RxJs and 1 second interval observable. 1 second is (sort of) UI refresh rate. It can be expressed using diagram:

Combined Stream

Combined Stream is a combination of last emits (completions) of Display Streams of all jobs in the batch. It can be expressed using diagram:

How to use it?

To use Jenkins Job Runner, first you need to install:

npm install jenkins jenkins-rxjs jenkins-jobs-runner

Create an instance of Job Batch Runner:

import { JenkinsRxJs } from 'jenkins-rxjs';
import { JobBatchRunner} from 'jenkins-jobs-runner';
const jenkinsRxJs = new JenkinsRxJs(...);
const jobBatchRunner = new JobBatchRunner(jenkinsRxJs);

Prepare JobBatchDescriptor array:

const jobBatchDescriptors = [
  {
    displayName: 'first group display name',
    jobDescriptor: [
      {
        displayName: 'first job of first group',
        opts: {
          name: 'jenkins-job-name',
          parameters: {
            firstParam: 'value-of-param'
          }
        },
      },
      {
        displayName: 'second one',
        opts: { ... },
      },
    ],
  },
  {
    displayName: 'second group',
    jobDescriptor: [
      {
        displayName: 'only job of a second group',
        opts: { ... },
      },
    ],
  },
];

Execute jobs:

jobBatchRunner.runBatches(builderResult)
  .then(() => console.log('end'));

That is it. jobBatchRunner return a promise when finished should you want to do something afterward.

Summary

To summarise, Jenkins Jobs Runner can be used to execute and display a status of batches of parallel jobs. It takes single array input and handles calls to Jenkins API, updates status and the UI. This makes it easy to integrate it with any workflow.

As a part of a Jenkins CLI, this lib handles jobs execution and displaying progress in the UI. This was the last part and concludes this series. Code of each part is available on GitHub to provide better insight.