Search Results for ""

Orb Authoring Process

Introduction

Once you have configured your platform to work with CircleCI orbs, you are ready to begin authoring your own orb. CircleCI has attempted to make this process simple and easy, eliminating any potential confusion by enabling you to use inline templates and other pre-configured templates to quickly author a new orb. The sections below describe the process of authoring your own orb.

Orbs Quickstart

Before you create your first orb, please see the following notes:

  • Orbs exist in namespaces.
  • Each organization or username can claim one unique namespace.
  • Namespaces are global within the CircleCI orb registry, so pick a unique name!
  • Only users with “owner”/”administrator” privileges within a given GitHub/Bitbucket organization can create a namespace linked to that organization.
  • Any org member can publish dev orbs, but only admins can create new orb names or publish production orbs.
  • When stored as a project environment variable or Contexts resource, an API token generated by an org admin can help automate the orb publishing process, enabling any org member to potentially publish a production orb by using the CircleCI CLI in a CircleCI job.
  • To use the orbs you create, you will need to enable the “Allow Uncertified Orbs” setting in the Security section of CircleCI’s Organization Settings page for your organization (https://circleci.com/[vcs]/organizations/[org-name]/settings#security).
  • If you are creating an orb, you can use development versions to avoid having your orb publicly/permanently listed in CircleCI’s orb registry before it is ready.

The following high-level steps will enable you to publish your first orb:

1) Claim a namespace (assuming you don’t yet have one). For example:

circleci namespace create sandbox github CircleCI-Public

In this example we are creating the sandbox namespace, which will be linked to the GitHub organization CircleCI-Public.

Note: When creating a namespace via the CircleCI CLI, be sure to specify the VCS provider.

2) Create the orb inside your namespace. For example:

circleci orb create sandbox/hello-world

3) Create the content of your orb in a file. You will generally do this in your code editor in a git repo made for your orb, but, for the sake of an example, let’s assume a file in /tmp/orb.yml could be made with a bare-bones orb like:

echo '{version: "2.1", description: "a sample orb"}' > /tmp/orb.yml

4) Validate that your code is a valid orb using the CLI. For example, using the path above you could use:

circleci orb validate /tmp/orb.yml

5) Publish a dev version of your orb. Assuming the above orb, it would look like this:

circleci orb publish /tmp/orb.yml sandbox/hello-world@dev:first

6) Once you are ready to push your orb to production, you can publish it manually using circleci orb publish or promote it directly from the dev version. In the case where you want to publish the orb, assuming you wanted to increment the new dev version to become 0.0.1, you can use:

circleci orb publish promote sandbox/hello-world@dev:first patch

7) Your orb is now published in an immutable form as a production version and can be used safely in builds. You can then pull the source of your orb using:

circleci orb source sandbox/hello-world@0.0.1

Designing Orbs

When designing your own orbs, make sure your orbs meet the following requirements:

  • Orbs should always use description. - Be sure to explain usage, assumptions, and any tricks in the description key under jobs, commands, executors, and parameters.
  • Match commands to executors - If you are providing commands, try to provide one or more executors in which they will run.
  • Use concise naming for your orb - Remember that use of your commands and jobs is always contextual to your orb, so you can use general names like “run-tests” in most cases.
  • Required vs. optional parameters - Provide sound default values of parameters whenever possible.
  • Avoid job-only orbs - Job-only orbs are inflexible. While these orbs are sometimes appropriate, it can be frustrating for users to not be able to use the commands in their own jobs. Pre and post steps when invoking jobs are a workaround for users.
  • Parameter steps are powerful - Wrapping steps provided by the user allows you to encapsulate and sugar things like caching strategies and other more complex tasks, providing a lot of value to users.

Refer to Reusing Config for details and examples of commands, executors and parameters in orbs.

When developing your own orb, you may find it useful to write an inline orb. The section below describes how you can write your own inline orb.

Writing Inline Orbs

Inline orbs can be handy during development of an orb or as a convenience for name-spacing jobs and commands in lengthy configurations, particularly if you later intend to share the orb with others.

To write inline orbs, place the orb elements under that orb’s key in the orbs declaration in the configuration. For example, if you want to import one orb and then author inline for another, the orb might look like the example shown below:

version: 2.1
description: # The purpose of this orb

orbs:
  my-orb:
    orbs:
      codecov: circleci/codecov-clojure@0.0.4
    executors:
      specialthingsexecutor:
        docker:
          - image: circleci/ruby:1.4.2
    commands:
      dospecialthings:
        steps:
          - run: echo "We will now do special things"
    jobs:
      myjob:
        executor: specialthingsexecutor
        steps:
          - dospecialthings
          - codecov/upload:
              path: ~/tmp/results.xml

workflows:
  main:
    jobs:
      - my-orb/myjob

In the example above, note that the contents of my-orb are resolved as an inline orb because the contents of my-orb are a map; whereas the contents of codecov are a scalar value, and thus assumed to be an orb URI.

Example Inline Template

When you want to author an orb, you may wish to use this example template to quickly and easily create a new orb with all of the required components. This example includes each of the three top-level concepts of orbs. While any orb can be equally expressed as an inline orb definition, it will generally be simpler to iterate on an inline orb and use circleci config process .circleci/config.yml to check whether your orb usage matches your expectation.

version: 2.1
description: This is an inline job

orbs:
  inline_example:
    jobs:
      my_inline_job:
        parameters:
          greeting_name:
            description: # a helpful description
            type: string
            default: olleh
        executor: my_inline_executor
        steps:
          - my_inline_command:
              greeting_name: <<parameters.greeting_name>>
    commands:
      my_inline_command:
        parameters:
          greeting_name:
            type: string
        steps:
          - run: echo "hello <<parameters.greeting_name>>, from the inline command"
    executors:
      my_inline_executor:
        parameters:
          version:
            type: string
            default: "2.4"
        docker:
          - image: circleci/ruby:<<parameters.version>>

workflows:
  build-test-deploy:
    jobs:
      - inline_example/my_inline_job:
          name: mybuild # best practice is to name each orb job
      - inline_example/my_inline_job:
          name: mybuild2
          greeting_name: world

Providing Usage Examples of Orbs

The examples stanza is available in configuration version 2.1 and later

As an author of an orb, you may wish to document examples of using it in a CircleCI configuration file, not only to provide a starting point for new users, but also to demonstrate more complicated use cases.

When you have completed authoring an orb, and have published the orb, the orb will be published in the Orb Registry. You will see your newly-created orb in the Orb Registry, which is shown below.

Orbs Registry image

Simple Examples

Below is an example orb you can use:

version: 2.1
description: A foo orb

commands:
  hello:
    description: Greet the user politely
    parameters:
      username:
        type: string
        description: A name of the user to greet
    steps:
      - run: "echo Hello << parameters.username >>"

If you would like, you may also supply an additional examples stanza in the orb like the example shown below:

version: 2.1

examples:
  simple_greeting:
    description: Greeting a user named Anna
    usage:
      version: 2.1
      orbs:
        foo: bar/foo@1.2.3
      jobs:
        build:
          machine: true
          steps:
            - foo/hello:
                username: "Anna"

Please note that examples can contain multiple keys at the same level as simple_greeting, allowing for multiple examples.

Expected Usage Results

The above usage example can be optionally supplemented with a result key, demonstrating what the configuration will look like after expanding the orb with its parameters:

version: 2.1

examples:
  simple_greeting:
    description: Greeting a user named Anna
    usage:
      version: 2.1
      orbs:
        foo: bar/foo@1.2.3
      jobs:
        build:
          machine: true
          steps:
            - foo/hello:
                username: "Anna"
    result:
      version: 2.1
      jobs:
        build:
          machine: true
          steps:
          - run:
              command: echo Hello Anna
      workflows:
        version: 2
        workflow:
          jobs:
          - build

Usage Examples Syntax

The top level examples key is optional. Usage example maps nested below it can have the following keys:

  • description: (optional) A string that explains the example’s purpose, making it easier for users to understand it.
  • usage: (required) A full, valid config map that includes an example of using the orb.
  • result: (optional) A full, valid config map demonstrating the result of expanding the orb with supplied parameters.

Next Steps