Use Orbs

Use Orbs

Already have a favorite orb? No need to re-invent the wheel, orbs can still be used with the CircleCI Config SDK.

While it is possible to package all of your config as JavaScript packages, and replace most CircleCI 2.1 config features with native JavaScript, many existing integrations already work really well and are actively maintained by the community.

The caveat - Orbs, being external YAML-based dependencies, can not provide type information to the Config SDK. This may cause issues if you are using TypeScript, or confusing in JavaScript. So we must (for now), manually provide some information about the orb to the Config SDK (in TS). We hope to maybe replace this with an NPX command which could automatically generate this information for us in the future.

Tutorial

Create the definition for the imported orb, to give our config app access to the orb's types (TypeScript) only). Here, we are importing the Slack orb, and since we will only be using a single command and modifying one parameter on that command, that is all we need to reference.

Create src/orbs/slack.ts

import * as CircleCI from "@circleci/circleci-config-sdk";

const slackOrb = new CircleCI.orb.OrbImport(
  "slack",
  "circleci",
  "slack",
  "volatile"
);
slackOrb.commands.notify = new CircleCI.orb.OrbRef(
  "notify",
  new CircleCI.parameters.CustomParametersList<CircleCI.types.parameter.literals.CommandParameterLiteral>(
    [new CircleCI.parameters.CustomParameter("template", "string")]
  ),
  slackOrb
);

export { slackOrb };

Typing is a little verbose, but necessary for now. We will be working on a way to automatically generate this information in the future.

Create Basic Config App

import * as CircleCI from "@circleci/circleci-config-sdk";
import { slackOrb } from "./orbs/slackOrb";

// Components
const config = new CircleCI.Config();
const dockerExec = new CircleCI.executors.DockerExecutor("cimg/base:stable");
const job = new CircleCI.Job("test", dockerExec);
const workflow = new CircleCI.Workflow("test", [job]);

// Add Orbs
config.importOrb(slackOrb);

// Add steps to job
job.addStep(new CircleCI.commands.Checkout());

/**
 * We will add the orb's `notify` command here in the next step
 */


// Build config
config.addJob(job);
config.addWorkflow(workflow);

// Print config
console.log(config.stringify());

We import the slackOrb OrbImport object we created in the previous step, and add it to our config. We only left out invoking the notify command to take a deeper look at it here.

Using Orb Components

In this case, we are using a command that comes from an orb. In CircleCI 2.1 config, we introduced the concept of "reusable" configuration, including "commands" which are a collection of steps that can be invoked in a job. Orbs contain these "reusable" commands, we will just need to cast the orb's definition of a command into a new Reused command, with the parameters we want to override.

// Add steps to job
job.addStep(new CircleCI.commands.Checkout());
job.addStep(
  new CircleCI.reusable.ReusedCommand(slackOrb.commands.notify, {
    template: "basic_success_1",
  })
);

Generate the Config

The config generated by this app will look like this:

version: 2.1
setup: false
orbs:
  slack: circleci/slack@volatile
jobs:
  test:
    docker:
      - image: cimg/base:stable
    resource_class: medium
    steps:
      - checkout
      - slack/notify:
          template: basic_success_1
workflows:
  test:
    jobs:
      - test

Note The order of the top-level keys is not guaranteed, and has no effect.