CircleCI Config Preview SDK

Disclaimer: This is preview software intended for those interested in seeing what we are working on with next-gen configuration. Use the configurations generated by this software at your own risk.

Thank you for participating in our preview of config improvements

As we prepare to launch a set of new configuration features we appreciate the opportunity to work with you in validating and improving on our design choices for the next major wave of CircleCI configuration improvements. If you were invited to the preview by your CircleCI account team. If you have stumbled upon this repository, we welcome you to look around and give us feedback by submitting issues on this repo.

What problems are we trying to solve?

1. Better DRY support The configuration in CircleCI 2.0 is designed to be highly deterministic. As a result, the syntax proved in many cases to be much more verbose and prone to too much boiler plate and repeated code blocks. We aim to provide better ways avoid repetitive build configuration.

2. Code reuse across projects We hear from a lot of customers that they want better ways to share configuration across projects. This repo introduces Orbs, reusable packages of parameterizable CircleCI configuration elements that can be added to the Orb registry for use across projects.

3. Easier path to common configuration We often hear that people want more off-the-shelf options to get their first useful builds flowing, especially for common platforms like Rails, Node, and they want better encapsulation of common tasks like deploying to Heroku or pushing to an S3 bucket.

Basic example

Using an orb in your build configuration might look something like:

version: 2
orbs:
  s3: circleci/aws-tools@1.4.2

jobs:
  deploy:
    executor: s3/default
    steps:
      - s3/deploy:
          from: "somepath/somefile"
          to: $S3BUCKETURI
          overwrite: false

The above imports the circleci/aws-tools orb at revision 1.4.2, then invokes a command called deploy from that orb, passing in three parameters.

The code in the orb might look like:

executors:
  default:
    parameters:
      tag:
        type: string
        default: "1.15"
    docker:
      - image: cibuilds/aws:<< parameters.tag >>
commands:
  deploy:
    description: "A simple encapsulation of doing an s3 sync"
    parameters:
      from:
        type: string
        description: A directory path local to the job to deploy to S3
      to:
        type: string
        description: A URI to an S3 bucket
      overwrite:
        type: boolean
        default: false
        description: Boolean value for whether to overwrite the files
    steps:
      - run:
          name: Deploy to S3
          command: "aws s3 sync << parameters.from >> << parameters.to >><<# parameters.overwrite >> --delete<</ parameters.overwrite >>"

Staying informed

There are two ways to stay up-to-date with changes we make to our new configuration features:

1. Watch this repo on GitHub
2. Get email updates from us about the configuration preview: https://circle.ci/2HbCmKq

Getting started

Please look over the docs in this repository to understand the details of the new configuration features.