arrai-innovations / circleci-orbs

Arrai Innovation's CircleCI Orbs

CircleCI Orbs

This repository contains circleci orbs that Arrai Innovations publishes to the CircleCI Orb registry. While available for public consumption, these are tailored towards our CI process. These orbs are published into the arrai namespace.

Note to contributors: The Orb Registry is public; private data should be passed via variables configured in the CI interface or stored in the appropriate private repo.

• Available Orbs
  • badass
  • eslint
  • flake8
  • github
  • npm
  • prettier
  • pypi
  • pytest
  • safety
  • sentry
  • utils
• Developing Orbs
• Publishing Orbs

Available Orbs

badass

This Orb provides an environment for running our BMS/Django tests. Not likely to be useful for testing Django instances not built or based on BMS. For a description of the Orb, refer to the generated documentation.

eslint

Runs eslint on project code. Note that any warnings are treated as job failures. For more details, refer to the generated documentation.

flake8

Provides functionality for running flake8 on project code. Everything is treated as an error. For a description of the Orb, available steps, parameters, etc, refer to the generated documentation.

github

Creates a release on GitHub. For information on configuration parameters, refer to the generated documentation.

npm

Provides npm utility functions. For information on available functions and configuration parameters, refer to the documentation.

prettier

Provides functionality for running prettier on project code. For more details, refer to the generated documentation.

pypi

Publishes python packages to a PyPI (or compatible) server. It does not include the build step. It is assumed that some other job builds the packages and stashes the dist folder in a cache. Refer to the example configuration on how this might look.

For information on configuration parameters, refer to the generated documentation.

pytest

Provides generic test environment for pytest based tests that have dependencies installed using pipenv. For more details, refer to the generated documentation.

safety

This is now somewhat miss-named; it provides jobs to run pipenv check against the installed project. For more details, refer to the generated documentation.

sentry

Publish releases to Sentry. Note that the create_release job uses the following defaults when creating releases:

• The project slug is assumed to be the same as the repository name.
• The release version is taken from the tag name.
• It is assumed that repositories have been configured within the Sentry organisation so that commits can be associated with the release. Refer to the Sentry documentation on this matter.

For information on how to override these defaults, refer to the generated documentation. An example configuration is provided in the examples folder.

utils

This orb provides utility functions such as status badging, file uploads, and ssh key import. This is required by the other orbs. For information on the available utility functions, refer to the documentation.

Developing Orbs

This repository uses git hooks via the node module husky. These hooks keep the orb .yml formatted using prettier. They also enforce our commit message rules via commitlint. Orbs are validated using the circleci cli tool, which must be installed beforehand. You can install these hooks by running the following command:

$ npm install

Publishing Orbs

There are a few things to keep in mind when publishing new Orbs to the registry. Orbs are to be published using semver. Versioning is taken care of automatically by specifying one of patch, minor, or major when publishing. Publishing a new release works by promoting a previously published dev version. Since references to Orbs are versioned, a new release has no impact on existing project configurations or Orbs.

In order to publish Orbs to the registry, install the circleci CLI application. Run circleci setup to configure the tool once installed.

If you are creating a new Orb, you must first create it in the registry: circleci orb create arrai/example. Skip this if you're updating an existing Orb.

After making the requisite changes, you can check for syntactic validity by running: circleci orb validate example.yml. Note that the registry will prevent you from publishing Orbs containing syntax errors.

You can then publish a dev version of your Orb: circleci orb publish example.yml arrai/example@dev:1. You can now reference this Orb in project-specific configs or other Orbs. Unlike release Orbs, development Orbs are mutable and will be deleted after 90 days.

Once you're ready to promote your Orb to release, determine whether this counts as a patch, minor, or major release; this will be passed into the promote command: circleci orb publish promote arrai/example@dev:1 patch. The command will return the version number used for the Orb; use this to reference the new Orb in your project CI configurations.