[Early Preview] CircleCI Config SDK + Visual Config Editor | Write config with code or drag and drop!

CircleCI Config SDK + Visual Config Editor | Write config with code or drag and drop!

The Community and Partner Engineering team at CircleCI is announcing two new open-source projects available in Early Access preview today!

:warning: During the preview period frequent and potentially breaking changes are expected

Table Of Contents

  • Visual Config Editor
    • Visually drag and drop CircleCI config elements on a node-graph editor and generate your CircleCI config YAML at the click of a button.
  • CircleCI Config SDK
    • Create and manage your CircleCI config with JavaScript and TypeScript (More languages coming soon).

Visual Config Editor

Visually drag and drop CircleCI config elements on a node-graph editor and generate your CircleCI config YAML at the click of a button.


GitHub Repo: GitHub - CircleCI-Public/visual-config-editor: Generate your CircleCI configuration files by building a visual map of your project's workflows.
Live App: CircleCI - Visual Config Editor


Animated preview:

Features:

  • Supports multiple Workflow tabs
  • Define and add reusable Executors and Jobs
  • Define complex parallel, sequential and branching Workflows
  • Supports all 2.0 commands (steps)

Coming Soon:

  • Config parsing a.k.a two-way binding
  • CircleCI 2.1 config features

CircleCI Config SDK

Create and manage your CircleCI config with JavaScript and TypeScript (More languages coming soon).


GitHub Repo: GitHub - CircleCI-Public/circleci-config-sdk-ts
Docs: Home · CircleCI-Public/circleci-config-sdk-ts Wiki · GitHub
API Docs: @circleci/circleci-config-sdk
NPM Package: @circleci/circleci-config-sdk - npm


Example

const CircleCI = require('@circleci/circleci-config-sdk');
// Instantiate new Config
const myConfig = new CircleCI.Config();
// Create new Workflow
const myWorkflow = new CircleCI.Workflow('myWorkflow');
myConfig.addWorkflow(myWorkflow);

// Create an executor instance
// Executors are used directly in jobs
// and do not need to be added to the config separately
const nodeExecutor = new CircleCI.executor.DockerExecutor('cimg/node:lts');

// Create Job and add it to the config
const nodeTestJob = new CircleCI.Job('node-test', nodeExecutor);
myConfig.addJob(nodeTestJob);

// Add steps to job
nodeTestJob
  .addStep(new CircleCI.commands.Checkout())
  .addStep(
    new CircleCI.commands.Run({
      command: 'npm install',
      name: 'NPM Install',
    }),
  )
  .addStep(
    new CircleCI.commands.Run({
      command: 'npm run test',
      name: 'Run tests',
    }),
  );

// Add Jobs to Workflow
myWorkflow.addJob(nodeTestJob);

// The `stringify()` function on `CircleCI.Config` will return the CircleCI YAML equivalent.
const MyYamlConfig = myConfig.stringify();

In the example above, the MyYamlConfig variable will contain the following CircleCI config:

version: 2.1
setup: false
jobs:
  node-test:
    docker:
      - image: cimg/node:lts
    resource_class: medium
    steps:
      - checkout: {}
      - run:
          command: npm install
          name: NPM Install
      - run:
          command: npm run test
          name: Run tests
workflows:
  myWorkflow:
    jobs:
      - node-test: {}

Be sure to see the included Samples and Wiki.

FAQ

See the FAQ on the GitHub Wiki: FAQ · CircleCI-Public/circleci-config-sdk-ts Wiki · GitHub

Use-Cases

We believe you’ll build amazing things with the Config SDK that we cannot even imagine yet. But if you’re looking for ideas, why not give one of these a shot?

Dynamic Config Generation

CircleCI recently released “setup workflows”, a feature that will essentially allow you to run an initial workflow that can set up a second and more substantial workflow. Currently, this feature is often used to conditionally run one of two or more statically generated configuration files.

The Config SDK can generate config files at run-time during the setup workflow phase using any JavaScript logic you can imagine.

See the proof of concept example here: circleci-config-sdk-ts/sample/01-dynamic-workflow-javascript at main · CircleCI-Public/circleci-config-sdk-ts · GitHub

Private, Packagable, Reusable Configuration

Have a particular command, executor, job, or even entire workflow you find yourself reusing over and over again? Consider creating a standard NPM package library for your projects with all of your commonly used CircleCI config

Many existing users may already be familiar with CircleCI’s Orbs, which provides packages of CircleCI config natively within the YAML config file. With the Config SDK, you can encapsulate any aspect of CircleCI config (including entire workflows!) and manage them with your favorite JavaScript package manager and repository such as NPM. This will also give you access to type definitions.

Tooling

Build tools for the browser and command-line using the SDK as a library. The visual config editor was built using the Config SDK.


Catch the live stream

10 Likes

Nice, finally a way to write the config in real code :raised_hands:

@KyleTryon which other languages do you plan to support apart from JS and TS?

2 Likes

:raised_hands: We’re excited to see what you do with it!

Python is by far our number one priority but we should be able to support C#, Java, and Python all at the same time. We are looking at using the JSII build system, which is built by AWS and enables the AWS CDK to support multiple languages.

We are working on implementing this now, you can view and track the progress on additional languages here: Feature: Multi-language support via aws/jsii · Issue #51 · CircleCI-Public/circleci-config-sdk-ts · GitHub

Currently, in version 0.4.0 Early Preview, full JSII language support is one of our 1.0.0 release goals.

Language Version
TypeScript 1.0.0
JavaScript 1.0.0
Python 1.0.0
Java 1.0.0
C# 1.0.0
Kotlin TBD
Go TBD

We will begin sharing roadmap timing/planning soon, this board will begin to populate of the course of this preview: 1.0.0 General Availability · GitHub

Also, we’d love to hear from you (and anyone reading this) what languages you would be interested in!

1 Like

Cool, thanks for the insights.

We’d love to see Kotlin support :slight_smile:

1 Like