Circle CI

Liatrio no longer recommends CircleCI. GitHub Actions or GitLab CI/CD is preferred over CircleCI¶

Steps to migrate from CircleCI to GitHub actions can be found here

CircleCI is a modern continuous integration and continuous delivery (CI/CD) platform. It's primary responsibilities include building, testing, and deploying software. CircleCI supports both Github and Bitbucket integration, allowing team members to get automatic builds after pushing code up to the VCS of choice.

Here at client-name, the Platform Engineering team has configured a Bitbucket project for your team to use. Any project that includes a .circleci/config.yaml will trigger new builds on CircleCI. There are numerous ways to configure pipelines, however we'll focus on providing information that will allow you to take advantage of resources provided within client-name. We'll first need to learn how to define a pipeline and the different parts that determine logic flow.

Pipelines¶

CircleCI pipelines are the full set of processes that get run when you push up new work on your projects. Pipelines contain workflows and workflows contain jobs that need to be run against your code. All pipelines are defined in your configuration file, stored in <project-root>/.circleci/config.yaml.

Orbs¶

Often times there will be a set of actions you need to repeat across projects or within an organization. An example would be publishing a Docker image to a remote registry. While this may require unique parameters from team-to-team, the overall logic flow will remain the same. This is where Orbs come in.

Orbs are reusable snippets of code that automate repeated processes. Orbs can be shared among a group of people with configured parameters that allow users to change inputs. Using the Orb pattern, an organization can share pipeline logic in a scalable fashion while also allowing each orb to have it's own development lifecycle complete with tests and scans.

Here's an example of pipeline that uses an orb to test a node project:

version: 2.1

orbs:
  node: circleci/node@x.y.z          ## Import the orb and pin version

workflows:
  test_my_app:
    jobs:
      - node/test:                   ## Invoke a job that is exposed by the orb
          version: <node-version>    ## Pass parameters to the orb

Jobs¶

CircleCI Job

CircleCI uses Jobs as the building blocks of your pipeline configuration. Each job contains a series of steps which run commands and/or scripts. This allows you to categorize a series of commands into a logical unit. For example, you may need to issue several shell commands to publish an artifact(zip up contents, push to remote store, and verify). Putting each of these steps into one Job allows you to put it all together in a single logical unit.

Executors and Images¶

We've discussed that Jobs are the building blocks of your pipeline, but you'll still need a host machine to execute your code. That's where Executors come into play. Each job that you define will run in a unique executor and issue each step inside this environment. An executor can be a Docker container or a virtual machine. This allows us to select executors that have required dependencies. For example, if you have a job that builds a node project you'd probably want to select an executor that has Node installed such as node-agent.

Workflows¶

Now that we have the individual parts to a pipeline, it's time to put it all together. Workflows define a list of jobs and the order in which they will be executed. You can run jobs concurrently, sequentially, on a schedule, or even with a manual gate.

workflows:
  build_and_test: # name of your workflow
    jobs:
      - build1
      - build2:
          requires:
           - build1 # wait for build1 job to complete successfully before starting
           # see circleci.com/docs/2.0/workflows/ for more examples.
      - build3:
          requires:
           - build1 # wait for build1 job to complete successfully before starting
           # run build2 and build3 concurrently to save time.

You can create multiple workflows to capture different logic paths for a project. A common use-case is creating a dev-workflow and a qa-workflow. This allows you to define jobs with parameters for your dev release and create a separate workflow that contains logic for your qa release.