CircleCI Server v3.x Orbs

Last updated
Tags Server v3.x Server Admin

This section describes how to manage orbs for an installation of server v3.x. Server installations include their own local orb registry. All orbs referenced in configs reference the orbs in the server orb registry. You are responsible for maintaining orbs. This includes copying orbs from the public registry, updating orbs that may have been copied prior, and registering your companies private orbs if they exist.

For information on orbs and related use cases see the Orb docs.

If you are looking for information on creating an orb, see the Introduction to Authoring Orbs.

Managing Orbs

Orbs are accessed via the CircleCI CLI. Orbs require your CircleCI user to be an admin. They also require a personal API token. Please ensure that you are using a personal API token generated after your user account is made an admin.

Providing a local repository location using the --host option allows you to access your local server orbs vs the public cloud orbs. For example, if your server installation is located at http://circleci.somehostname.com, then you can run orb commands local to that orb repository by passing --host http://cirlceci.somehostname.com.

List available orbs

To list available public orbs, visit the orb directory or run:

circleci orb list

To list available private orbs (registered in your local server orb repository) run:

circleci orb list --host <your server install domain> --token <your api token>

Import a public orb

To import a public orb to your local server orb repository:

circleci admin import-orb ns[orb[@version]] --host <your server installation domain> --token <your api token>

Fetch a public orb’s updates

To update a public orb in your local server orb repository with a new version, run:

circleci admin import-orb ns[orb[@version]] --host <your server installation domain> --token <your api token>

Using orbs behind a proxy

When importing orbs, the CLI must be able to talk to the server installation and to circleci.com. If you want to do this when using a server installation behind a proxy, the CLI needs to be configured to use the proxy to make those requests to circleci.com and to not proxy requests to the server install. Here is an example of how this could look:

export NO_PROXY=server.example.com
export HTTPS_PROXY=http://proxy.example.com:3128
export HTTP_PROXY=http://proxy.example.com:3128
circleci admin import-orb ns[orb[@version]] --host <your server installation domain> --token <your api token>


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.