Brigade: Document loading JS files into `brigade.js`

[technosophos]

It is fairly easy to store additional JS files in your VCS repo, and then load it into the brigade.js using require(). But this is not documented.

[vdice]

I believe @radu-matei may have some more extensive examples, but my rudimentary exercise for including local js yielded the following:

brigade.js has:

const { events, Job}  = require("brigadier");
const { Helper } = require("/vcs/helpers");

events.on("exec", (e, project) => {
  try {
    var helper = new Helper(e, project, Job);
    helper.slackNotify("===> exec event received!");
  } catch (e) {
    console.log(e);
  }
})

(where I wrapped the main functionality in a try/catch to capture errors that didn't seem to properly bubble up otherwise... need to investigate why this was needed.)

helpers.js has:

class Helper {
  constructor(event, project, Job) {
    this.event = event;
    this.project = project;
    this.Job = Job;
  }

  slackNotify(message) {
    var slack = new this.Job("slack-notify", "technosophos/slack-notify:latest");

    slack.env = {
      SLACK_WEBHOOK: this.project.secrets.SLACK_WEBHOOK,
      SLACK_USERNAME: "BrigadeBot",
      SLACK_TITLE: "Build " + this.event.buildID,
      SLACK_MESSAGE: message,
      SLACK_COLOR: "#00ff00"
    };
    slack.tasks = ["/slack-notify"];

    if (this.event.cause && this.event.cause.trigger != "success") {
      slack.env.SLACK_COLOR = "#ff0000"
    }

    slack.run();
  }
}

exports.Helper = Helper;

A few notes from my exercise:

1. I seem to only be able to fetch local JS files when supplying the full path of /vcs/path/to/file. I believe this is because Brigade currently doesn't have logic to copy non-brigade.js files into /home/src/dist in the worker pod (hence, require("./helpers") doesn't work.) If this reasoning is correct, I wonder if we should consider an enhancement such that relative pathing can work?

2. Since my helpers.js file creates a Job, I needed to pass Job in. It didn't appear possible to add a const { Job } = require("brigadier"); as usual at the top of these non-brigade.js scripts. Again, it would be nice to avoid needing to pass in brigadier classes via constructor or function invocation. Ideas on how we might do so and/or what I might've been missing here?

[radu-matei]

We might be able to avoid copying the files by overriding the import path (pretty much like we do for require(@azure/brigadier), so that any local import path is re-written in the worker to have its full /vcs path.

In your example, you would import it in brigade.js like:

const { Helper } = require("./helpers"); → const { Helper } = require("./vcs/helpers");

(This way, you also get IntelliSense in the IDE when writing the file).

EDIT: this strategy seems to be coming along nicely.

[dgkanatsios]

(This way, you also get IntelliSense in the IDE when writing the file).

and avoid the red squiggly lines on VS Code (cannot find this file/library etc.)!

[radu-matei]

Also, for reference, I've been putting together a library of commonly used Brigade jobs. It is intended to be used as an NPM package, loaded into brigade.json.

Now, to showcase both scenarios (local deps + NPM packages loaded into brigade.json), I put together this repo.

I'll play with both ideas some more today, and let's chat again at standup about this.

[vdice]

Yes! So excited for that brigade-utils library, Radu! Definitely can't wait to streamline our brigade.js files to reuse code that can live in this library. (Will try to wait post-1.0 😄 )

[radu-matei]

Yay, fixed in #787.