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.

Best Practices

Do not publish sensitive data within an orb, even a private orb. CircleCI does not support orb deletion, even in the case of accidental publishing of sensitive information.

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?

The 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:

cierlceci 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:

cirecleci orb source $NAMESPACE/$ORB [flags]

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

https://circleci.com/developer/orbs/orb/$NAMESPACE/$ORB