Orb Tools Orb

An orb for orb authors - provides a full suite of jobs for packing, validating, reviewing, testing and deploying your orbs to the orb registry.

Usage

The orb-tools orb is a key component of the "Orb Development Kit". For the full documentation for developing orbs, see the Intro to Authoring an Orb documentation.

When you initialize a new orb project using the Orb Development Kit, a customized .circleci/config.yml file is created containing a full CI pipeline for building, testing, and publishing your orb which utilizes the "orb-tools" orb for the majority of these functions. You can find the config template here.

Once automatically configured, on each code push to your repo, CircleCI will trigger the pipeline defined in the .circleci/config.yml file, which will execute (among several others) the orb-tools orb's jobs.

When you are ready to publish a new version of your orb, you can create a new release on GitHub and/or push a semantically versioned tag.

Quick Docs

• Getting Started
• Creating an Orb
• Testing an Orb
• Publishing an Orb

Migrate From Older Orb Tools Versions

Follow the migration guide.

Local Usage

A subset of the orb-tools orb jobs and scripts can be ran locally. It is useful to be able to lint, shellcheck, and review your orbs locally, before committing. With this setup, it is possible to test your code locally, but integration tests of the built orb will be ran on CircleCI.

Local Linting

The orb-tools orb's orb-tools/lint job uses a utility yamllint, which can be downloaded an ran locally, or you can invoke the job locally with the CircleCI CLI.

Assuming you ./circleci/config.yml file appears similar to the one in this repository, you will have imported the orb-tools orb and defined the orb-tools/lint job in a workflow. Using the CLI from this directory, use the following command to locally lint your orb:

CircleCI Local Linting

$ circleci local execute --job orb-tools/lint

YamlLint Local Linting

$ yamllint ./src

Note: you will need a .yamllint file in the current directory to run the yamllint command. This will also be generated for you by the Orb Development Kit. Preview the file in the Orb Project Template.

Local Shellcheck

Shellcheck is a static analysis tool for shell scripts, and behaves like a linter for our shell scripts. Which of course can also be ran locally, or if defined within your configuration file, you can invoke the job locally with the CircleCI CLI.

CircleCI Local Shellcheck

$ circleci local execute --job shellcheck/check

You can not however pass in parameters to skip specific checks. Use the Shellcheck CLI locally for more control when running locally.

Shellcheck CLI Local Shellcheck

$ shellcheck ./src/scripts/*.sh --exclude SC2148,SC2038,SC2086,SC2002,SC2016

Local Review

The review job is a suite of Bash unit tests written using bats-core, a test automation framework for Bash. Each test focuses on checking for a best practice in the orb. The tests can be executed directly with the bats CLI, or you can invoke the job locally with the CircleCI CLI.

CircleCI Local Review

$ circleci local execute --job orb-tools/review

Note: You will always see a failure at the end of this job when ran locally because the job contains a step to upload test results to CircleCI.com, which is not supported in the local agent.

Bats CLI Review

You can also install the bats-core package locally and run the tests with the bats CLI.

$ bats ./src/scripts/review.bats

Contributing

We welcome issues to and pull requests against this repository!

For further questions/comments about this or other orbs, visit CircleCI's orbs discussion forum.