Managing URL orbs allow-lists
Introduction
The allow-list is a security mechanism that restricts orb URL references to only approved URL prefixes, providing security and access control for organizations using private or external orbs.
This guide explains how to add, view, or delete allow-lists in the CircleCI Web App and via the API.
Managing allow-lists
Each allow-list entry contains three components:
-
Name - A descriptive identifier for the entry
-
URL prefix - The approved URL pattern that orb references must match (must use HTTPS and end with /)
-
Auth - The authentication method to use.
-
In the CircleCI Web App, the available values are:
None,GitHub OAuth,GitHub App, orBitbucket OAuth. -
In the API, the available values are:
none,github-oauth,github-app, orbitbucket-oauth.
-
For an organization to use a URL orb, there must be at least one allow-list entry whose URL prefix matches the beginning of the orb’s URL. If no matching entry exists, the orb reference will be blocked.
The allow-list applies organization-wide. Once configured, all projects within that organization can use orbs from the approved URL prefixes.
Adding a URL orb allow-list entry
View the organization’s URL orb allow-lists
Delete a URL orb allow-list entry
Limitations and caveats
-
The URL orb allow-list is limited to at most 5 entries.
-
A single config may use no more than 50 URL orbs in total, whether referenced directly or indirectly in a hierarchy.
-
A hierarchy of URL orbs may not exceed a depth of 5 orb references.
-
The
GitHub OAuthandBitbucket OAuthauth types assume that any member of the organization known to CircleCI has permission to fetch the URL orb. If this is not true then seemingly arbitrary failures to fetch URL orbs will occur. TheGitHub Appauth type does not have this limitation. -
Once an orb has been fetched the content is cached for 5 minutes. This is both to reduce load on the remote system hosting the orb, and to improve build times for busy projects.
-
GitLab authentication is currently not supported.