CircleCI Orbs

In the latest update of circleCI they have included an interesting inclusion — orbs.

Photo by Wayan Aditya on Unsplash

What is an orb?

The best link I can think of to an orb is an npm package (or library to be more general). You import packages and then the package's functionality is available to you to use in your file (or globally depending on how you’ve installed it).

Why is this useful?

As with importing libraries the usefulness is in reducing the actual lines of code in your file. It also means you don’t have to write out a program yourself and can instead use someone else’s (which in theory should be more optimized and better since it should be maintained by open source developers).

Okay great now we have an understanding let’s do an example to hammer the point home. I will assume you have a general understanding of circleCI and how it works. We will be using the AWS S3 circleCI orb.

First create a .circleci folder with a file named config.yml, this is the file we will add all the code to.

We must use the latest version of circleCI at the top of the page which is

version: 2.1

Now we include the AWS S3 orb.

version: 2.1 
orbs:   
  aws-s3: circleci/aws-s3@1.0.13

where aws-s3 is the variable name we will use to call the orb. The version number is 1.0.13. Currently, it doesn’t seem like you can use @latest (or something similar) to make sure you are using the latest version. Therefore, it’s important to make sure you regularly check for newer versions and update when available.

We will run it in using an arbitrary node container as follows

version: 2.1
orbs:   
  aws-s3: circleci/aws-s3@1.0.13
executors:
  node-container:
    docker:
      - image: circleci/node:10.16.3-browsers

Now to use the orb (I will assume you have added your AWS credentials to circle already)

version: 2.1
orbs:   
  aws-s3: circleci/aws-s3@1.0.13
executors:
  node-container:
    docker:
      - image: circleci/node:10.16.3-browsers
jobs:
  executer: node-container
  steps:
    - checkout
    - run: mkdir myBucket && echo "hello world" > /   
           myBucket/build_asset.txt
    - aws-s3/sync:
        from: myBucket
        to: 's3://my-s3-bucket/prefix'
        arguments: | 
          --acl public-read --cache-control "max-age=86400"
        overwrite: true

Here I’m running a job with some steps which will be executed inside the node-container. Let’s take a closer look at what is happening the steps.

- checkout is a formality

- run: mkdir myBucket && echo "hello world" > / myBucket/build_asset.txt is bash and creates a folder called myBucket with a file called build_asset.txt which contains the text hello world.

- aws-s3/sync:
    from: myBucket
    to: 's3://my-s3-bucket/prefix'
    arguments: | 
      --acl public-read --cache-control "max-age=86400"
    overwrite: true

In this step we use the sync option (exactly what it does can be found here) of the aws-s3 orb. We are syncing the newly created myBucket with the bucket contained in S3 called my-s3-bucket. We pass arguments that allow public read access and a cache TTL of 86400 seconds (24 hours). We have also added the command overwrite:true which means files on the s3 bucket will be overwritten given files have the same name.

To summarize my-s3-bucket will now contain all the contents of myBucket where the contents will be publicly readable, with a cache TTL of 24 hours and any files with the same name would have been overwritten.

And that, in a nutshell, is how circleCI orbs work — almost exactly like libraries.

You can find more info (other functionality, options etc… ) about the aws-s3 orb here.

P.S. Here’s all the code we managed to avoid having to write

Looks like medium cut me off here’s the link to access all the code https://gist.github.com/DominicGBauer/35f2e2e941e200e377c95d6b6b72a294 (I do feel this helped my point though :P )