Skip to content

Pipeline definition helpers

See the complete type definition on DenoLand

UPGRADE

When needed, upgrade helpers to latest version.

sh
deno cache --reload pipelight.ts
deno cache --reload pipelight.ts

What is it ?

tl;dr

Helpers are functions that bulk generate bash commands!

Helpers are Javascript/Typescript functions that will do some heavy lift to easily define complex pipelines. There is actually 3 helpers groups:

  • common helpers (ease pipeline definition)
  • docker helpers (ease docker infrastructure management)
  • template helpers (customizable prebuilt pipelines)

With each goup made on top of the previous one.

Born from a dire need of simplicity

Pipelight core features allow users to write all-mighty pipelines in whichever manner is possible. However being such a low level tool comes with its drawbacks.

Even if you enjoy writing functions that simplify the automation of trivial but difficult tasks such as containerisation, virtualisation, testing and deployment. Pipeline definition can quickly become time consuming.

As the main goal of automation is to save you time, pipelight comes with already made functions that are called helpers.

Helpers are made to standardize and structurize pipeline definition to finally ship great functions to ease trivial pipeline writing.

Embrace programmation (again)

For example, the following pipeline creates a docker images and run the containers based on those images.

::: ino You don't need to know what is docker to understand what helpers bring on the table in the the following example. :::

Instead of writing your commands explicitly, the helper generates the appropriate bash commands so you don't have to.

ts
steps: [
  {
    name: "build_images",
    commands: [
      "docker build --tag image_name -f Dockerfile.example . " 
      // Repeat for every images 
    ]
  },
  {
    name: "run_containers",
    commands: [
      "docker run image_name container_name" 
      // Repeat for every container 
    ]
  }
];
steps: [
  {
    name: "build_images",
    commands: [
      "docker build --tag image_name -f Dockerfile.example . " 
      // Repeat for every images 
    ]
  },
  {
    name: "run_containers",
    commands: [
      "docker run image_name container_name" 
      // Repeat for every container 
    ]
  }
];

ts
steps: [
  {
    name: "build_images",
    commands: [
      ...docker.images.create() 
    ]
  },
  {
    name: "build_images",
    commands: [
      ...docker.containers.build() 
    ]
  }
];
steps: [
  {
    name: "build_images",
    commands: [
      ...docker.images.create() 
    ]
  },
  {
    name: "build_images",
    commands: [
      ...docker.containers.build() 
    ]
  }
];

Delicious Syntax 🤌

Import needed helpers from the deno repository.

ts
import { helper_name } from "https://deno.land/x/pipelight/mod.ts";
import { helper_name } from "https://deno.land/x/pipelight/mod.ts";

Use them in your pipeline definition and enjoy the syntax.

ts
step("build images and run containers", () => [
    ...docker.images.create(),
    ...docker.containers.create()
]),
step("build images and run containers", () => [
    ...docker.images.create(),
    ...docker.containers.create()
]),

A thrilling example

Aside from the boring Docker Object definition, this is what the core of a pipeline made with helpers looks like.

Here we use the pipeline, step, ssh, and docker helpers.

This pipeline builds some custom docker images and sends them to remote, Then, on the remote, it replaces the old existing containers with the newly created ones to finally run them.

ts
// Docker object with previously defined params
const docker = new Docker(params);

pipeline("deploy_containers_to_remote", () => [
  // Create images locally and send them to remote
  step("build and send images", () => [
    ...docker.images.create(),
    ...docker.images.send(host)
  ]),

  // Build containers on remote and run them
  step("update containers", () =>
    ssh(host, () => [
      ...docker.containers.remove(),
      ...docker.containers.create()
    ])
  )
]);
// Docker object with previously defined params
const docker = new Docker(params);

pipeline("deploy_containers_to_remote", () => [
  // Create images locally and send them to remote
  step("build and send images", () => [
    ...docker.images.create(),
    ...docker.images.send(host)
  ]),

  // Build containers on remote and run them
  step("update containers", () =>
    ssh(host, () => [
      ...docker.containers.remove(),
      ...docker.containers.create()
    ])
  )
]);

As you can see above, helpers combination allows us to write understandable and straightforward code to generate powerfull pipelines.

DEBUG

You can check auto-generated commands by inspecting the resulting pipeline.

sh
pipeline inspect
pipeline inspect