Terminology

• Workflow: bundles together a collection of jobs to be run at a certain point in time. Caching persists data between a job’s run across workflow runs, and artifacts are stored data after a workflow run.
• Job: a collection of steps, typically either commands to be run or orb scripts to call. The steps bundled under the same job execute together and can more or less be thought of as a single unit. Caching lets you save data between the same job across different workflow runs.
• Step: a step is any list item under the steps: directive within a named job. Steps themselves are more or less the atomic, indivisible units that define a job’s execution. This includes things like the checkout step, arbitrary run: <cmd> steps, etc.

All in all, the main workflow, job, and step terminology is pretty much a simple hierarchy of units, building up to high-level workflow unit (or pipeline).

Orbs

CircleCI Orbs are essentially maintained bundles of useful commands for certain pipelines. It’s pretty much a simple namespace of callable scripts that help reduce boilerplate associated with common jobs for a certain environment. For example, a simple Python pipeline might be to checkout the package, install its dependencies in an environment, and save that cache for the next build. Without an orb, you might have a config file like this:

steps:
      - checkout
      - run: sudo chown -R circleci:circleci /usr/local/bin
      - run: sudo chown -R circleci:circleci /usr/local/lib/python3.6/site-packages
      - restore_cache:  # ensure this step occurs *before* installing dependencies
          key: deps9-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
      - run:
          command: |
            sudo pip install pipenv
            pipenv install
      - save_cache:
          key: deps9-{{ .Branch }}-{{ checksum "Pipfile.lock" }}
          paths:
            - ".venv"
            - "/usr/local/bin"
            - "/usr/local/lib/python3.6/site-packages"

With orbs, however, these commands get wrapped up under simple names to make things cleaner for the developer. We could instead have a config file that looks something like this:

orbs:
  python: circleci/[email protected]

steps:
      - checkout
      - python/load-cache
      - python/install-deps
      - python/save-cache
      - run:
          command: |
            # pytest would be a dep in requirements.txt
            pytest

and do virtually the same thing as the config file above.

Notes

• working_directory defaults to ~/project
• the checkout method is a bit odd, it will not clone the repo into a separate directory; it just spews the repo contents out in the current directory. Can specify a path: <path> key to tell where the repo should be cloned relative to the working_directory.