Create, test, and use URL orbs

4 days ago · 16 min read

Cloud

URL orbs are not available if your code is stored in a GitLab repository.

This guide covers how to create URL orbs. URL orbs are reusable CircleCI configuration stored in an accessible location like a Git repository. You can use URL orbs to share configuration across your organization.

Introduction

URL orbs are reusable packages of CircleCI configuration. They can be stored in any accessible location (such as a Git repository or object storage) and referenced directly via URL in your CircleCI configuration files.

URL orbs contain the same reusable configuration elements as inline orbs and registry orbs:

The key differences:

Unlike registry orbs (published to the Orb Registry), URL orbs are not published and are controlled by your organization’s allow-list.
Unlike inline orbs (defined in a single project’s config), URL orbs can be shared across your organization.

This guide covers URL orbs. For information on creating registry orbs, see Create, Test, and Publish a Registry Orb. For information on creating inline orbs, see Create an Inline Orb.

For a complete comparison of all three orb types, see the Orb Types Comparison section.

Prerequisites

Before creating a URL orb:

Ensure you are in a position to configure your organization’s URL orb allow-list. See Managing URL Orbs Allow-Lists for steps.
Ensure you have access to a hosting location for your orb files (GitHub repository, S3 bucket, etc.).
Be familiar with Reusable Configuration concepts.

URL orb structure

URL orbs are YAML files that follow the CircleCI orbs specification. Here is a basic structure:

version: 2.1

description: >
  A description of what your orb does.

commands:
  # Your reusable commands

jobs:
  # Your reusable jobs

executors:
  # Your reusable executors

Creating a URL orb

1. Create the orb file

Create a YAML file with your orb configuration. For example, create a file named platform-tools.yml:

Example platform-tools.yml file to be used as a URL orb

version: 2.1

description: >
  Platform tools and utilities for our organization.

commands:
  install-cli:
    description: Install our platform CLI tool
    parameters:
      version:
        type: string
        default: "latest"
        description: Version of the CLI to install
    steps:
      - run:
          name: Install Platform CLI
          command: |
            echo "Installing platform CLI version << parameters.version >>"
            # Add your installation commands here

  deploy:
    description: Deploy application to our platform
    parameters:
      environment:
        type: string
        description: Target environment (staging, production)
      api-key:
        type: env_var_name
        default: PLATFORM_API_KEY
        description: Environment variable containing API key
    steps:
      - run:
          name: Deploy to << parameters.environment >>
          command: |
            # Add your deployment commands here
            echo "Deploying to << parameters.environment >>"

jobs:
  deploy-app:
    description: Complete deployment job
    executor: default
    parameters:
      environment:
        type: string
        description: Target environment
    steps:
      - checkout
      - install-cli
      - deploy:
          environment: << parameters.environment >>

executors:
  default:
    description: Default executor for platform jobs
    docker:
      - image: cimg/base:2026.01

2. Store the orb in an accessible location

Store your orb file in a location accessible via HTTPS. Common options include:

GitHub repository.
GitLab repository.
Bitbucket repository.
AWS S3 bucket.
Other object storage.

For the purposes of this guide, we will use a GitHub repository.

Store your orb in a GitHub repository, as follows:

Example GitHub repository structure for storing URL orbs

my-org-orbs/
├── README.md
├── platform-tools.yml
└── security-scanner.yml

The raw URL will be:

Example raw URL for a URL orb in a GitHub repository

https://raw.githubusercontent.com/<org>/<repo>/<branch>/platform-tools.yml

If you choose another hosting option, the raw URL will be different. For example:

GitLab: https://gitlab.com/<org>/<repo>/-/raw/<branch>/<file>.yml
Bitbucket: https://bitbucket.org/<org>/<repo>/raw/<branch>/<file>.yml
AWS S3: https://s3.amazonaws.com/<bucket>/<path>/<file>.yml
Other object storage: Any HTTPS-accessible location.

3. Configure the allow-list

Your organization administrator must add the URL prefix to the allow-list before the orb can be used.

For example, if your orb is at:

Example URL for a URL orb in a GitHub repository

https://raw.githubusercontent.com/my-org/orbs/main/platform-tools.yml

The allow-list entry should include the prefix:

Example URL prefix for a URL orb in a GitHub repository

https://raw.githubusercontent.com/my-org/orbs/

See Adding a URL Orb Allow-List Entry for detailed instructions.

Step 4: Use the orb in your configuration

Reference your URL orb in a CircleCI configuration file:

version: 2.1

orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/main/platform-tools.yml

workflows:
  deploy:
    jobs:
      - platform/deploy-app:
          environment: staging

Testing your URL orb

Validate YAML

Before using your orb, validate the YAML syntax:

If you do not have the CircleCI CLI installed, first see the Installing the Local CLI page.

circleci orb validate platform-tools.yml

Test in a pipeline

Create a test configuration to verify your orb works correctly:

version: 2.1

orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/main/platform-tools.yml

workflows:
  test-orb:
    jobs:
      - test-commands

jobs:
  test-commands:
    docker:
      - image: cimg/base:stable
    steps:
      - platform/install-cli:
          version: "1.0.0"
      - run:
          name: Verify installation
          command: |
            # Add verification commands
            echo "CLI installed successfully"

Trigger a pipeline (via push, API, or web app) to test your orb, observe the results in the CircleCI web app.

Updating URL orbs

To update a URL orb:

Make changes to your orb YAML file.
Commit and push the changes to your repository.
The updated orb will be available at the same URL.

URL orbs are cached for 5 minutes after being fetched. Changes may not be immediately visible in running pipelines.

Versioning URL orbs

URL orbs do not use semantic versioning. You can implement your own versioning strategy using Git features:

Using branches

Use different branches for different versions:

# Production
orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/main/platform-tools.yml

# Development
orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/develop/platform-tools.yml

Using tags

Create Git tags for stable versions:

# Specific version
orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/v1.0/platform-tools.yml

Using commit hashes

Reference specific commits for immutability:

orbs:
  platform: https://raw.githubusercontent.com/my-org/orbs/abc123def456/platform-tools.yml

Best practices

Add descriptions to all components:

Example command with description

commands:
  deploy:
    description: Deploy application to the platform
    parameters:
      environment:
        type: string
        description: Target environment (staging or production)
    steps:
      # ...

Make your orb components flexible with parameters:

Example command with parameters. A parameter is used to pass the version of the tool to install.

commands:
  install-tool:
    parameters:
      version:
        type: string
        default: "latest"
      install-path:
        type: string
        default: "/usr/local/bin"
    steps:
      # Installation steps using parameters

Never hard-code secrets. Use the env_var_name parameter type:

Example command with secrets. The API key is stored in an environment variable.

commands:
  authenticate:
    parameters:
      api-key:
        type: env_var_name
        default: API_KEY
        description: Environment variable containing the API key
    steps:
      - run:
          name: Authenticate
          command: |
            # Use ${!parameter} to get the value from the environment variable
            API_KEY_VALUE=${!<< parameters.api-key >>}
            # Use API_KEY_VALUE in your commands

Include documentation in your repository, for example:

Add a README explaining what the orb does and how to use it.
Include usage examples.
Document all parameters and their effects.
Keep a changelog of updates.

Limitations

URL orbs have the following limitations:

Limited to 50 URL orbs per configuration file.
Maximum nesting depth of 5 for URL orb hierarchies.
Cached for 5 minutes after fetching.

For full details, see URL Orb Limitations.

[path]

[title]

Create, test, and use URL orbs

Introduction

Prerequisites

URL orb structure

Creating a URL orb

1. Create the orb file

2. Store the orb in an accessible location

3. Configure the allow-list

Step 4: Use the orb in your configuration

Testing your URL orb

Validate YAML

Test in a pipeline

Updating URL orbs

Versioning URL orbs

Using branches

Using tags

Using commit hashes

Best practices

Limitations

See also