CircleCI Logo
Navigation Menu Icon

Managing URL orbs allow-lists

Language Icon 8 days ago
Cloud
Contribute Go to Code

The URL orb 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

  • CircleCI web app

  • API

  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
Using server? If you are using CircleCI server, replace https://circleci.com with your server hostname when interacting with the CircleCI API.

  1. Set up your API authentication. Steps are available in the API Developers Guide.

  2. Send a POST request to the Create a new URL orb allow-list entry endpoint to add an allow-list entry, with a JSON map containing name, prefix, and auth keys, as the request body.

Example
curl -X POST https://circleci.com/docs/api/private/organization/ec1234ec-7d44-xxx-b468-7e552408ee32/url-orb-allow-list \
  --header "Circle-Token: ${CIRCLE_TOKEN}" \
  --header 'content-type: application/json' \
  --data '{"name": "Private URL Orbs", "prefix": "https://raw.githubusercontent.com/my-org/private-orbs/", "auth": "github-app"}'
Example response
{
  "id":"6a7e25f1-6da7-xxxx-9fb0-69e7b92f6xxx",
  "message":"Created."
}

View the organization’s URL orb allow-lists

  • CircleCI web app

  • API

  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
Using server? If you are using CircleCI server, replace https://circleci.com with your server hostname when interacting with the CircleCI API.

  1. Set up your API authentication. Steps are available in the API Developers Guide.

  2. Send a GET request to the List the entries in the org’s URL Orb allow-list endpoint to view the organization’s URL orb allow-lists.

Example:

curl -X GET https://circleci.com/docs/api/private/organization/ec1234ec-7d44-xxx-b468-7e552408ee32/url-orb-allow-list \
  --header "Circle-Token: ${CIRCLE_TOKEN}"
Example response
{
  "items": [
    {
       "id": "6a7e25f1-6da7-xxxx-9fb0-69e7b92f6xxx",
       "name": "Private URL Orbs",
       "prefix": "https://raw.githubusercontent.com/my-org/private-orbs/",
       "auth": "github-oauth"
    }
  ]
}

Delete a URL orb allow-list entry

  • CircleCI web app

  • API

  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
Using server? If you are using CircleCI server, replace https://circleci.com with your server hostname when interacting with the CircleCI API.

  1. Set up your API authentication. Steps are available in the API Developers Guide.

  2. Send a DELETE request to the Remove an entry from the org’s URL orb allow-list endpoint to delete the allow-list entry.

Example
curl -X DELETE https://circleci.com/docs/api/private/organization/ec1234ec-7d44-xxx-b468-7e552408ee32/url-orb-allow-list/6a7e25f1-6da7-xxxx-9fb0-69e7b92f6xxx \
  --header "Circle-Token: ${CIRCLE_TOKEN}"
Example response
{
  "id": "6a7e25f1-6da7-461b-9fb0-69e7b92f6xxx",
  "message": "Deleted."
}

Configure allow-lists for common scenarios

This section provides guidance on setting up URL orb allow-lists for different use cases.

Choose the right authentication type

The authentication type you select depends on whether the orb repository is public or private, and which version control system you use.

Use None when:

  • Your orb is hosted in a public repository.

  • Your orb is hosted in a publicly accessible location (for example, AWS S3 with public read access)

Use GitHub App when:

  • Your orb is hosted in a private GitHub repository and you have the CircleCI GitHub App installed for your organization.

The GitHub App authentication type is the preferred method for private GitHub repositories because it provides more reliable access control and does not depend on individual user permissions.

Use GitHub OAuth when:

  • Your orb is hosted in a private GitHub repository and you do not have the CircleCI GitHub App set up.

Use Bitbucket OAuth when:

  • Your orb is hosted in a private Bitbucket repository

Construct URLs for orb repositories

The URL prefix you configure must match the beginning of your orb’s full URL. The following examples show how to construct URLs for different hosting platforms.

  • GitHub

  • GitLab

  • Bitbucket

  • AWS S3 and other object storage

For a file located at orbs/my-orb.yaml in a repository called my-org/my-orbs-repo:

Using a branch reference
https://raw.githubusercontent.com/my-org/my-orbs-repo/refs/heads/main/orbs/my-orb.yaml
Using a specific commit SHA
https://raw.githubusercontent.com/my-org/my-orbs-repo/abc123def456/orbs/my-orb.yaml

To find the correct URL for a file in GitHub:

  1. Navigate to the file in your GitHub repository.

  2. Select the Raw button.

  3. Copy the URL from your browser’s address bar.

When you configure your allow-list entry, use the URL prefix that matches all orbs you want to reference. For example, to allow all orbs in the orbs/ directory of your repository, use:

Allow-list entry for all orbs in the orbs/ directory
https://raw.githubusercontent.com/my-org/my-orbs-repo/refs/heads/main/orbs/

Branch references versus commit SHAs

  • Use branch references (for example, refs/heads/main) when you want orb updates to automatically take effect in your pipelines.

  • Use commit SHAs when you want to pin to a specific version of the orb content.

  • Remember that CircleCI caches fetched orbs for five minutes, so changes to branch-referenced orbs may not appear immediately.

For a file located at orbs/my-orb.yml in a GitLab repository called my-org/my-orbs-repo:

Using a branch reference:

https://gitlab.com/my-org/my-orbs-repo/-/raw/main/orbs/my-orb.yml

Using a specific commit SHA:

https://gitlab.com/my-org/my-orbs-repo/-/raw/abc123def456/orbs/my-orb.yml
GitLab authentication is not currently supported. Only use public GitLab repositories with the None auth type.

To find the correct URL for a file in GitLab:

  1. Navigate to the file in your GitLab repository.

  2. Select the Open Raw button.

  3. Copy the URL from your browser’s address bar.

Branch references versus commit SHAs

  • Use branch references (for example, refs/heads/main) when you want orb updates to automatically take effect in your pipelines.

  • Use commit SHAs when you want to pin to a specific version of the orb content.

  • Remember that CircleCI caches fetched orbs for five minutes, so changes to branch-referenced orbs may not appear immediately.

For a file located at orbs/my-orb.yml in a Bitbucket repository called my-org/my-orbs-repo:

Using a branch reference:

https://bitbucket.org/my-org/my-orbs-repo/raw/main/orbs/my-orb.yml

Using a specific commit SHA:

https://bitbucket.org/my-org/my-orbs-repo/raw/abc123def456/orbs/my-orb.yml

To find the correct URL for a file in Bitbucket:

  1. Navigate to the file in your GitLab repository.

  2. Select the Open raw button.

  3. Copy the URL from your browser’s address bar.

Branch references versus commit SHAs

  • Use branch references (for example, refs/heads/main) when you want orb updates to automatically take effect in your pipelines.

  • Use commit SHAs when you want to pin to a specific version of the orb content.

  • Remember that CircleCI caches fetched orbs for five minutes, so changes to branch-referenced orbs may not appear immediately.

For orbs hosted in AWS S3 or other object storage systems:

Using a specific bucket and object name:

https://s3.amazonaws.com/my-bucket/orbs/my-orb.yml

Ensure your bucket and objects have the appropriate permissions to allow CircleCI to fetch the content. Use the None auth type for publicly accessible URLs.

Use orbs from both public and private repositories

If you want to use URL orbs from both public and private repositories in the same version control system, you need to create multiple allow-list entries with the same URL prefix but different authentication types.

For example, to use orbs from both public and private GitHub repositories in the my-org organization:

  1. Create an allow-list entry with:

  2. Create a second allow-list entry with:

When CircleCI encounters a URL orb reference, it tries each matching allow-list entry until it successfully fetches the orb content. This approach lets you use orbs from both public and private repositories in the same organization.

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.