Orbs: Public vs. Private vs. Unlisted

Since introducing Private Orbs, there have been many questions around the differences between Orbs. This guide should help distinguish those answers and help highlight some of the useful differences between them. 

To create an orb, you will need to install the CircleCI CLI. This will provide you with the necessary commands to create, update, and modify both Public and Private Orbs.

Public Orbs

How are they created?

Using the CircleCI CLI you can use the following command and follow our automated Orb Authoring Process

circleci orb init /path/to/myProject-orb

Alternatively, we do have a manual orb authoring process that still uses the CircleCI CLI but doesn't use the orb development kit.

Who can use them?

These orbs are public and can be used by any user or organization.

Where are they found?

Public Orbs can be found on our Orb Registry or by using the following command:

circleci orb list <namespace>

Private Orbs

How are they created?

Similar to Public Orbs, but limited to paid customers

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

Who can use them?

Private Orbs can only be used in projects within the same organization that created the Orb.

Where are they found?

Private Orbs will not be listed in the orb registry (however, this is a future planned feature) and will only be listed by the following command:

circleci orb list <namespace> --private

Unlisted Orbs

How are they created?

Unlisted Orbs are not themselves an Orb, but rather the state of a Private or Public orb. The state of an Orb can be changed with the following command:

circleci orb unlist <namespace>/<orb> <true|false> [flags]

Who can use them?

Unlisted Orbs do not change in functionality, only in visibility. An unlisted Public Orb will still be available to be used by any user or organization that has implemented it into their project. Similarly, any project can use their own organization's Private Orbs, even if they are unlisted. 

Where are they found?

Unlisted Orbs will not appear in the Orb Registry or with orb list command. However, the Public Orb's source can still be viewed if the Orb's name is known by using:

circleci orb source <namespace>/<orb> [flags]

or, for Public Orbs, you can still access the Orb source page by using the following link format:




Use caution when unlisting Private Orbs. Currently the orb source and orb info commands do not work for any Private Orbs, regardless if they are listed or unlisted. So unless the Private Orb name is documented before it is unlisted, you will not be able to find the orb through the Orb Registry or the CircleCI CLI. If you believe this happened to you, please create a Support Ticket.

Was this article helpful?
1 out of 2 found this helpful



Article is closed for comments.