The Brigade.js API

This document describes the public APIs typically used for writing Brigade.js. It does not describe internal libraries, nor does it list non-public methods and properties on these objects.

An Brigade JavaScript file is executed inside of a cluster. It runs inside of a Node.js-like environment (with a few libraries blocked for security reasons). It uses Node 8.

High-level Concepts

An Brigade JS file is always associated with a project. A project defines contextual information, and also dictates the security parameters under which the script will execute.

A project may associate the script to a repository, where a repository is typically a VCS reference (e.g. a git repository). Each job will, by default, have access to the project’s repository.

Brigade files respond to events. That is, Brigade scripts are typically composed of one or more event handlers. When the Brigade environment triggers an event, the associated event handler will be called.

The brigadier Library

The main library for Brigade is called brigadier. The Brigade runtime grants access to this library.

const brigadier = require('brigadier')

It is considered idiomatic to destructure the library on import:

const { events, Job, Group } = require('brigadier')

Some objects described in this document are not declared in brigadier, but are exposed via brigadier.

The BrigadeEvent class

The BrigadeEvent class describes an event. Typically, it is exposed to the script via a callback handler.

events.on("pull", (brigadeEvent, project) => {})

An instance of an BrigadeEvent has the following properties:

The revision object

The revision object has the following properties:

If the revision object is not provided, it may be interpreted as master, or the head of the main branch. The default value is not guaranteed to be master in future versions.

The Cause class

A Cause is attached to an BrigadeEvent, and describes the event that caused this event. It has the following properties:

The after and error built-in events will set a Cause on their BrigadeEvent objects.

The events Object

Within brigadier, the events object provides access to the main event handler.

events.on(eventName: string, callback: (e: BrigadeEvent, p: Project) => {})

The events.on() function is the way event handlers are registered. An on() method takes two arguments: the name of the event and the callback that will be executed when the named event fires.

events.on("push", (e, p) => {
  console.log(p.name)
})

events.has(eventName: string): boolean

events.has is used to see if an event handler was registered already.

The Group class

The Group class provides both static methods and object methods for working with groups.

The static runAll(Job[]): Promise<Result[]> method

The runAll method runs all jobs in parallel, and returns a Promise that waits until all jobs are done and then returns the collected results.

This is useful for running a batch of jobs in parallel, but waiting until they are complete before continuing with another operation.

The static runEach(Job[]): Promise<Result[]> method

This runs each of the given jobs in sequence, blocking on each job until it is complete. The Promise will return the collected results.

The new Group(Job[]): Group constructor

Create a new Group and optionally pass it some jobs.

The add(Job...) method

Adds one or more Job objects to the group.

The length(): number method

Return how many jobs are in the group.

The runAll(): Promise<Result[]> method

Runs all of the jobs in the group in parallel. When the Promise resolves, it will wrap all of the results.

Functionally, this is equivalent to the static runAll method.

The runEach method

Runs each of the jobs in sequence (synchronously). When the Promise resolves, it will wrap all of the results.

Functionally, this is equivalent to the static runEach method.

The Job class

The Job class describes a job that can be run.

constructor new Job(name: string, image?: string, tasks?: string[], imageForcePull?: boolean): Job

The constructor requires a name parameter, and this must be unique within your script. It must be composed of the characters a-z, A-Z, 0-9, and -. Additionally, the - cannot be the first or last character, and the name must be at least two characters.

Optionally, you may specify the container image (e.g. node:8, alpine:3.4). The container image must be fetchable by the runtime (Kubernetes). If no container is specified here or with Job.image, a default image will be loaded.

Optionally, you may specify a list of tasks to be run inside of the container. If no tasks are specified here or with Job.tasks, the container will be run with its defaults.

These two are equivalent:

var one = new Job("one")
one.image = "alpine:3.4"
one.tasks = ["echo hello"]

var two = new Job("two", "alpine:3.4", ["echo hello"])

Properties of Job

The job.podName() method

This returns the name of the pod that was started during job.run(). It will return an empty string before run() is called.

The job.run(): Promise<Result> method

Run the job, returning a Promise that returns when the job is complete.

The JobCache class

A JobCache object provides preferences for a job’s usage of a cache.

Caches are disabled by default.

Properties:

The JobDockerMount class

The JobDockerMount controls whether, and how, a Docker socket is mounted to the job. Docker sockets are used for building Docker images. Because they mount to the host, using a Docker socket is considered dangerous. Thus, to use the Docker mount, the job must be put into privileged mode.

Properties:

The JobHost class

A JobHost object provides preferences for the host upon which the job is executed.

The JobStorage class

The KubernetesConfig class

A KubernetesConfig object has the following properties:

The Result class

This wraps the result of a Job run.

The toString(): string method

This returns the result as a string.

The Project class

Properties:

Secrets (project.secrets) are passed from the project configuration into a Kubernetes Secret, then injected into Brigade.

So helm install brigade-project --set secrets.foo=bar will add foo: bar to project.secrets.

The Event object

The Event object describes an event.

Properties:

The Job object

To create a new job:

j = new Job(name)

Parameters:

Properties:

It is common to pass data from the e.env Event object into the Job object as is appropriate:

events.push = function(e) {
  j = new Job("example")
  j.env = { "DB_PASSWORD": project.secrets.dbPassword }
  //...
  j.run()
}

The above will make $DB_PASSWORD available to the “example” job’s runtime.

Methods:

The Repository Class

The Repository class describes a project’s VCS repository (if provided).