Docs
Start Building for Free
CircleCI.comAcademyBlogCommunitySupport

Managing URL orbs allow-lists

1 month ago2 min read
Cloud
Server v4+
On This Page

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, or Bitbucket OAuth.

    • In the API, the available values are: none, github-oauth, github-app, or bitbucket-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

  1. Navigate to the Organization Settings  Orbs.

  2. In the Allowed URL Orb prefixes section, select Add.

  3. Fill out the Name, URL Prefix, and Auth fields.

  4. Select Add URL Prefix.

Add URL Prefix modal

View the organization’s URL orb allow-lists

  1. Navigate to Organization Settings  Orbs.

  2. Scroll to the Allowed URL Orb prefixes section.

  3. Existing allow-list entries are displayed in the table.

Allow-list in Organization settings > Orbs

Delete a URL orb allow-list entry

  1. Navigate to Organization Settings  Orbs.

  2. Scroll to the Allowed URL Orb prefixes section.

  3. Select the Delete icon next to the allow-list entry to delete.

Delete URL Prefix modal

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 OAuth and Bitbucket OAuth auth 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. The GitHub App auth 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.

Suggest an edit to this page

Make a contribution
Learn how to contribute

Still need help?

Ask the CircleCI community
Join the research community
Visit our Support site