Pipelyne

A theoretical experiment to enable writing a CI/CD pipeline in good ol' JavaScript.

"Atwood would be proud"

Benefits

1. Run your pipeline locally
2. Involve developers by using their favourite language
3. Run JavaScript instead of Bash
4. Distribute your pipeline
5. Write once, export for multiple CI runners

Scope

Base

• Consumer able to define pipeline stages via .stage() (see usage)
• Consumer able to define pipeline jobs within a stage via .job() (see usage)
• Consumer able to load a Pipelyne by specifying a file path URI (see usage)
• Consumer able to load a an externally defined Pipelyne (see usage)
• Consumer able to add manually input bash scripts via .run() (see usage)

Variable Management

• Consumer able to set and read a variable all during runtime (see usage)

File Operations

• Consumer able to read contents of a file into memory (see usage)

NPM Convenience Methods

• Consumer able to install NPM dependencies (see usage)
• Consumer able to publish to NPM (see usage)
• Consumer able to run an NPM script (see usage)

Exporting from Pipelyne

• Consumer able to export pipeline to Travis format (see usage)

Future

• Consumer able to do file manipulation
• Consumer able to set file ownership permissions
• Consumer able to set file modification/execution permissions
• Consumer able to run NPM scripts from package.json
• Consumer able to publish to DockerHub
• Consumer able to do a Git push to repository
• Consumer able to export pipeline to GitLab format

Installation

# with npm < 5 
npm i pipelyne --save;
# or with npm > 5 
npm i pipelyne;
# or with yarn 
yarn add pipelyne

Usage

Importing & Initialisation

import {Pipelyne} from 'pipelyne';
 
const pipeline = new Pipelyne();

Defining a Stage

pipeline.stage('stage name', {/* stage options */})

Defining a Job

pipeline
  .stage('stage name', {/* stage options */})
  .job('job name', {/* job options */})

Defining a Shell Command

pipeline
  .stage('stage name', {/* stage options */})
  .job('job name', {/* job options */})
  .run('pwd') // runs the `pwd` command

Reading file contents into memory

Runs at run-time, not build-time

pipeline
  .stage('stage name')
  .job('job name')
  .readFile('./path/to/file', 'testvar');
 
pipeline.getVariable('testvar'); // undefined
 
pipeline.execute();
 
pipeline.getVariable('testvar'); // contents of file

Set and read variable at runtime

pipeline
  .stage('stage name')
  .job('job name')
  .readFile('./path/to/file', 'testvar')
  .print('file contents are:', pipeline.ref('testvar'));
 
pipeline.getVariable('testvar'); // undefined
 
pipeline.execute(); // observe "file contents are: ..." output

Loading external Pipelyne via path

pipeline.load('./path/to/pipelyne.js');

NOTE: The file at ./path/to/pipelyne.js should export a pipelyne property.

Loading external Pipelyne

pipeline.load(require('./path/to/pipelyne.js').pipelyne);

NOTE: The loaded pipelyne should be an instance of Pipelyne.

Installing NPM Dependencies

pipeline
  .stage('stage')
  .job('job')
  // doing a development dependencies install
  .npm.install()
  // doing a production dependencies install
  .npm.install({production: true});

Publishing to NPM

pipeline
  .stage('stage')
  .job('job')
  .npm.publish();

Running an NPM Script

pipeline
  .stage('stage')
  .job('job')
  // npm run build
  .npm.run('build')
  // npm run test -- --watch
  .npm.run('test', {args: '--watch'});

Exporting Pipelyne for Travis

const fs = require('fs');
const path = require('path');
// ...
// export the pipeline into a file named .travis.yml
fs.writeFileSync(
  path.join(__dirname, './.travis.yml'),
  pipeline.exportFor('travis')
);

API

Pipelyne Instance

A Pipelyne instance exposes the following methods:

Configuration

RunnableOptions

StageOptions

Stage options includes all the configurations in RunnableOptions as well as the following:

JobOptions

Job options includes all the configurations in RunnableOptions as well as the following:

CommandOptions

Command options includes all the configurations in RunnableOptions.

No extra configurations are available.

PipelyneStringFormat

This can be one of "json" or "overview".

Contributing

Fork, make changes, push, merge request with master, wait for tests to pass. You know the drill (:

License

This package is licensed under the MIT license.

See the attached license file for details.

ChangeLog

Cheers