CircleCI Config SDK

Create and manage your CircleCI configuration files with JavaScript and TypeScript.

Table of Contents

• CircleCI Config SDK
  • Table of Contents
  • Getting Started
    • Installation
      • Usage
    • Example
  • Getting Help
    • Resources
• Contributing
• Related

Getting Started

📖 Getting Started Wiki

📖 SDK API Docs

💻 Examples

Installation

Using npm:

$ npm i @circleci/circleci-config-sdk

Using yarn:

$ yarn add @circleci/circleci-config-sdk

Usage

In Browser:

import CircleCI from '@circleci/circleci-config-sdk';

In Node.js:

const CircleCI = require('@circleci/circleci-config-sdk');

Example

Generate a CircleCI config using TypeScript/Javascript, properly typed for full IntelliSense support.

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.executors.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();

// Save the config to a file in Node.js or the browser. Note, use in the browser requires user interaction.
myConfig.writeFile('config.yml');

MyYamlConfig will hold the following string (A valid 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: {}

Getting Help

This open-source project utilized GitHub issues and project boards to manage requests and support.

If you can not find an answer to your question in an existing issue, you may open a new issue with the appropriate template. Issues are the best way for the CircleCI team and the open-source community to track and interact with your questions.

Resources

Consider checking the following common resources before opening a new issue.

• CircleCI Config Reference
• Config SDK API Documentation
• FAQ

Contributing

This repository welcomes community contributions! See our CONTRIBUTING.md for guidance on configuring your development environment and how to submit quality pull requests.

Related

• Visual Config Editor