Create an orb
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 GitHub.com.
Following this tutorial you will:
Create a GitHub repo for your orb.
Add templated orb config, based on your requirements.
Set up a CI/CD pipeline for orb development and put restrictions on who can contribute towards the development of your orb.
At the end of the tutorial you will be ready to configure your orb.
These steps are also outlined in the following video.
A GitHub account connected to your CircleCI account. See the Sign up and try page for steps to get set up.
$ 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
|Once an orb is created it cannot be deleted. Orbs are semver compliant, and each published version is immutable. Publicly released orbs are potential dependencies for other projects. Therefore, allowing orb deletion would make users susceptible to unexpected loss of functionality.|
1. Create a new repo
Create a new, empty, GitHub repository. The name of your repository is not critical, but something similar to "myProject-orb" is recommended.
|Ensure that the repository is completely empty. Uncheck any options such as "Add a README.md" or "Choose a license".|
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.
| It is not necessary to pull down the orb repository. This will be completed when you run |
2. Initialize your orb
Open a terminal and initialize your new orb project using the
orb init CLI command as shown below. 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 project repo.
| If you are using CircleCI server, you should ensure the |
| Once an orb is initialized, it cannot be switched from public to private or vice versa. Please make sure to add the |
3. Choose the fully automated orb setup option
? 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.
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
README.md files within each directory that contain helpful information specific to the contents of each directory. You will also be asked for the remote git repository URL that you obtained back in step 1.
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
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.
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
8. Enable Dynamic Configuration
Using the orb development kit makes use of Dynamic configuration, you will need to enable this feature. You will receive an error on your first pipeline that will state that this feature is not yet enabled.
Following the Getting started with dynamic config in CircleCI guide, open the Project Settings page for your orb on CircleCI, navigate to the Advanced tab, and click on the Enable dynamic config using setup workflows button.
Once enabled, all future commits to your project will run through the full pipeline and test your orb. You could manually re-run the pipeline at this point, but since you are only working with sample code at this moment, it is not necessary.
9. 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, and 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, find information on deploying changes on the Orb publishing process page.
Help make this document better
This guide, as well as the rest of our docs, are open source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.