@balena/ci-task-runner v0.2.26-renovate-non-major-da3053768f16377e60509c5fd1e733785725328c

CI Task Runner

Tool for running tasks inside of the balenaCI Docker Compose sut container.

Usage

This tool can either be used as a command-line tool or programatically.

Command line tool example:

$ ci-task-runner help
$ ci-task-runner validate --config /tmp/config.yml
$ ci-task-runner run --config /tmp/config.yml

Programatically:

const TaskRunner = require('@balena/ci-task-runner')

const taskRunner = new TaskRunner('/tmp/config.yml')
taskRunner.start()

Setup

To begin using this tool with your project, a YAML configuration file defining tasks is necessary must first be prepared. Once this has been created and added to your project's repository, install @balena/ci-task-runner in your sut container as a globally available command with npm i -g @balena/ci-task-runner and set your container's CMD to execute something like ci-task-runner run --config /path/to/my/config.yml.

Example Config

tickTimeout: 5
retryTimeout: 120
attemptsDefault: 3
tasks:
  - name: 'my-first-task'
    description: 'My first task'
    command: 'ls'
    cwd: '/usr/src/jellyfish'
    required: true
  - name: 'my-second-task'
    description: 'My second task'
    command: 'echo $MY_TASK_VAR'
    cwd: '/usr/src/jellyfish'
    required: false
    attempts: 1
    environment:
      - name: 'MY_TASK_VAR'
        value: 'foobar'
    dependencies:
      - 'my-first-task'

Documentation

A module for running a set of CI tasks.

• ci-task-runner
  • module.exports ⏏
    • new module.exports(attemptsDefault, environment, options)
    • .TaskRunner
      • new exports.TaskRunner(configPath)
      • .start()
      • .monitor()
      • .onSuccess()
      • .onFailure()
    • .isDirectory(location) ⇒ Boolean
    • .isWritable(location) ⇒ Boolean
    • .isWritableFile(location) ⇒ Boolean
    • .validate(config)
    • .cleanString(original) ⇒ String
    • .getTimestamp() ⇒ Number

module.exports ⏏

Kind: Exported class
Summary: CI task
Access: public

new module.exports(attemptsDefault, environment, options)

Example

const task = new Task(3, {
  FIRST_VAR: 'first_value',
  SECOND_VAR: 'second_value'
}, {
  name: 'example-task',
  attempts: 10,
  description: 'Example task',
  command: 'ls -al',
  cwd: '/tmp',
  required: true,
  dependencies: [
    'other-task'
  ]
})
task.start()

module.exports.TaskRunner

Kind: static class of module.exports
Summary: CI task runner
Access: public

• .TaskRunner
  • new exports.TaskRunner(configPath)
  • .start()
  • .monitor()
  • .onSuccess()
  • .onFailure()

new exports.TaskRunner(configPath)

Example

const runner = new Runner('/usr/src/jellyfish/ci/tasks/config.yml')
runner.start()

taskRunner.start()

Kind: instance method of TaskRunner
Summary: Start tasks as background processes

taskRunner.monitor()

Kind: instance method of TaskRunner
Summary: Monitor running tasks for completion and/or inactivity

taskRunner.onSuccess()

Kind: instance method of TaskRunner
Summary: Execute onSuccess event handler

taskRunner.onFailure()

Kind: instance method of TaskRunner
Summary: Execute onFailure event handler

module.exports.isDirectory(location) ⇒ Boolean

Kind: static method of module.exports
Summary: Check if a given path is a directory that exists or not
Returns: Boolean - check result

Example

const location = '/tmp'
if (exports.isDirectory(location)) {
  console.log(`${location} is a directory`)
}

module.exports.isWritable(location) ⇒ Boolean

Kind: static method of module.exports
Summary: Check if a given path is writable
Returns: Boolean - check result

Example

const isWritable = exports.isWritable('/tmp')
console.log(isWritable)

module.exports.isWritableFile(location) ⇒ Boolean

Kind: static method of module.exports
Summary: Check if a given file path is writable
Returns: Boolean - check result

Example

const isWritable = exports.isWritableFile('/tmp/test.json')
console.log(isWritable)

module.exports.validate(config)

Kind: static method of module.exports
Summary: Validate a config object against the schema definition

Example

const config = yaml.safeLoad(fs.readFileSync(configPath, 'utf8'))
utils.validate(config)

module.exports.cleanString(original) ⇒ String

Kind: static method of module.exports
Summary: Clean up an environment variable string, remove whitespace and quotes
Returns: String - cleaned up string

Example

const result = exports.cleanString(process.env.MY_STRING_VAR)

module.exports.getTimestamp() ⇒ Number

Kind: static method of module.exports
Summary: Generates and returns the current unix timestamp
Returns: Number - current unix timestamp