CircleCI Config SDK + Visual Config Editor | Write config with code or drag and drop!
The Config SDK and Visual Config Editor are now available in G.A.!
The information below is now outdated.
The Community and Partner Engineering team at CircleCI is announcing two new open-source projects available in Early Access preview today!
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
Edit: Aug/18/22
The Visual Config Editor is now Generally Available. Read more here: Visual Config Editor for CircleCI is now "GA"
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: Generate CircleCI Configuration YAML from JavaScript or TypeScript. Use Dynamic Configuration and the Config SDK together for live generative config.
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: https://github.com/CircleCI-Public/circleci-config-sdk-ts/tree/main/sample/01-dynamic-workflow-javascript
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.
