Start Building for Free

Create an orb

1 month ago5 min read
Server v4.x
Server v3.x
On This Page

This tutorial guides you through creating a new orb using the orb development kit. The starting point is creating a new repository on

Following this tutorial you will:

  • Create a GitHub repository for your orb.

  • Add template orb configuration, based on your requirements.

  • Set up a CI/CD pipeline for orb development, and put restrictions on who can contribute.

At the end of the tutorial you will be ready to configure your orb.

These steps are also outlined in the following video:

Create and initialize an orb


  • A GitHub account connected to your CircleCI account. See the Sign up and try page for steps to get set up.

  • Set up the CircleCI CLI on your local machine with a personal access token. Ensure you are using the latest version of the CircleCI CLI. You must be using version v0.1.17087 or later.

    circleci update
    circleci version
  • Register a namespace for your GitHub organization. Ensure the organization on GitHub is the owner for the CircleCI namespace for which you are developing your orb. This will be automatically configured correctly if you are using your own personal organization and namespace.

Create your orb

1. Create a new repository

Create a new, empty, GitHub repository. The name of your repository is not critical, but something similar to "myProject-orb" is recommended.

New GitHub repository

Once complete, you should see the generated git URL. Note it down, you will need it in step 4. You can select SSH or HTTPS, whichever you can authenticate with.

Orb registry

2. Initialize your orb

Open a terminal and initialize your new orb project using the orb init CLI command as shown below. Use the --private flag if required. The circleci orb init command is called, followed by a path to create and initialize for your orb project. It is best practice to use the same name for this directory and the git repository.

  • To initialize a public orb:

    circleci orb init </path/to/myProject-orb>
  • To initialize a private orb:

    circleci orb init </path/to/myProject-orb> --private

3. Choose the fully automated orb setup option

Choose Yes, walk me through the process. when prompted.

? Would you like to perform an automated setup of this orb?:
   ▸  Yes, walk me through the process.
      No, I will handle everything myself.

When choosing the fully automated option, the orb template is downloaded and automatically modified with your customized settings. The project will be followed on CircleCI with an automated CI/CD pipeline included.

For more information on the included CI/CD pipeline, see the Orb publishing process page.

GitHub App integration additional steps

If your GitHub account is authorised with CircleCI using the GitHub App integration, you will need to follow some extra steps, as listed below. To find out if you authorized through the GitHub OAuth app or the CircleCI GitHub App, see the GitHub App integration page.

  • When prompted, Are you using GitHub or Bitbucket or GitHub app (if GH App use circleci as the entry)?, enter circleci.

  • When prompted, Enter your circleci username or organization, you will need to inspect the URL from the CircleCI web app and provide the org ID portion:

    1. Navigate to the CircleCI web app

    2. The URL will be in the form:<org-ID-string>. The last string is the org ID that you need.

  • At the end of the automated set up process you will receive an error: Error: Could not follow project. At this point you need to push your project up to GitHub, and set it up in a new CircleCI project. Steps for creating a new project can be found on the Create a project page.

  • Once you have your orb pushed up to GitHub and your project set up, you will need to make a few manual updates:

    • In config.yml and test-deploy-yml, update vcs_type: << pipeline.project.type >> to be vcs_type: github.

    • In src/@orb.yml update source_url: <orb URL> to be source_url: "<your-github-user-or-org-name>/<your-orb-repo-name>".

4. Follow the prompts to set up your orb

In the background, the orb init command copies and customizes the orb template based on your inputs. There are detailed files within each directory that contain helpful information specific to the contents of each directory. You will be asked for the remote git repository URL that you obtained back in step 1.

The orb template contains a full CI/CD pipeline (described in orb publishing process), which automatically packs, tests, and publishes your orb.

In the setup process you will be asked if you would like to save your personal API Token into an orb-publishing context. Saving this token is necessary for publishing development and production versions of your orb. If you have already made an orb in the past, you can skip this step, as the context will already exist.

5. Restrict who can trigger jobs for the orb

Use security groups to limit access to users that are allowed to trigger jobs. Only these users will have access to the private personal API token.

Contexts can be located by navigating to Organization Settings > Contexts in the web app. After creating your orb, you will have a new context called orb-publishing. Click into orb-publishing and add a Security Group.

Secure contexts

6. Push changes to GitHub

During the setup process, the orb init command prepares your automated orb development pipeline. The modified template code produced by the CLI must be pushed to the repository before the CLI can continue and automatically follow your project on CircleCI.

Run the following command from a separate terminal when prompted to do so, substituting the name of your default branch:

git push origin <default-branch>

Once complete, return to your terminal and confirm the changes have been pushed.

7. Complete the setup

Once the changes have been pushed, return to your terminal and continue the setup process. The CLI will now automatically follow the project on CircleCI, and attempt to trigger a pipeline to build and test your orb with sample code.

You will be provided with a link to the project building on CircleCI where you can view the full pipeline. You should also see the CLI has automatically migrated you into a new development branch, named alpha. You can use any branch naming you would like, you do not need to exclusively develop on alpha.

8. Develop your orb

From a non-default branch (you will be moved to the alpha branch automatically at setup), begin modifying the sample orb code to fit your requirements. On each push, your orb will be automatically built and tested. More information on developing your orb can be found on the Orb authoring process page.

Be sure to view the .circleci/test-deploy file to view how your orb components are being tested. You can modify your tests as you change your orb. Learn more about testing your orb on the Orb testing methodologies page.

When you are ready to deploy the first production version of your orb, head to the Orb publishing process page.

Build and test an orb

Suggest an edit to this page

Make a contribution
Learn how to contribute