Working with Orbs

1. Understanding Orbs

Property	Description	Example
orb	Reference to a CircleCI orb	`orbs:`
version	Version of the orb to use	`version: 2.1`

Example: Using an Orb in a Configuration

version: 2.1
orbs:
  aws-cli: circleci/aws-cli@1.0.0
workflows:
  deploy:
    jobs:
      - aws-cli/deploy

Note: Orbs are reusable configuration templates that can be shared across projects.

Key Features of Orbs

Reusable configuration components
Versioned and published to CircleCI's registry
Can include jobs, commands, executors, and parameters

2. Importing Orbs

Property	Value	Description
orbs	`circleci/python@1.2.3`	Import an orb by name and version
orbs	`circleci/python@volatile`	Import the latest version of an orb

Example: Importing an Orb

version: 2.1
orbs:
  python: circleci/python@1.2.3

workflows:
  main:
    jobs:
      - python/test

Note: Orbs must be declared at the top level of your config file.

3. Using Certified Orbs

Orb	Description	Version	Usage
circleci/python	Python orb for running tests and building projects	`5.2.0`	`orbs: python: circleci/python@5.2.0`
circleci/node	Node.js orb for running tests and building projects	`5.0.0`	`orbs: node: circleci/node@5.0.0`
circleci/aws-cli	Orb to interact with AWS services	`5.0.1`	`orbs: aws-cli: circleci/aws-cli@5.0.1`

Example: Using Python Orb

version: 2.1
orbs:
  python: circleci/python@5.2.0
jobs:
  test:
    executor: python/default
    steps:
      - checkout
      - python/pytest

Note: Certified orbs are maintained by CircleCI and undergo security checks.

4. Specifying Orb Versions

Version Type	Specification Method	Notes
Orb Version	`orbs:` section in config `circleci/orb-name@version`	Use `@latest`, `@stable`, or a specific version tag
Orb Hash	`orbs:` section in config `circleci/orb-name@sha256:hash`	Ensures deterministic orb usage, useful for CI stability
Orb Range	`orbs:` section in config `circleci/orb-name@^1.2.0`	Allows minor version updates, but not breaking changes

Example: Using Specific Orb Version

version: 2.1
orbs:
  node: circleci/node@5.0.0
workflows:
  build:
    jobs:
      - node/test

Example: Using Orb Hash

version: 2.1
orbs:
  node: circleci/node@sha256:abc123def456...
workflows:
  build:
    jobs:
      - node/test

Note: Using @latest or @stable can lead to unexpected behavior if orb authors make breaking changes. It's recommended to pin versions for production workflows.

5. Finding Orbs

Example: Searching for Orbs

circleci orb list

Orb	Description	Version	Tags
circleci/python	Python orb for testing and building Python projects	`1.2.0`	NEW
circleci/node	Node.js orb for testing and building Node.js projects	`4.1.0`	DEPRECATED
circleci/aws-cli	Orb for working with AWS CLI in CircleCI	`2.0.0`	BETA

How to Find Orbs

Use circleci orb list to see all available orbs
Browse the CircleCI Developer Hub for community and official orbs
Search by tags or keywords to narrow down results

6. Viewing Orb Documentation

Example: Accessing Orb Documentation

# View documentation for a specific orb
circleci orb info <orb-name>/<orb-version>

# List all orbs in a namespace
circleci orb list <namespace>

# View the latest version of an orb
circleci orb info <orb-name>/latest

Command	Description	Notes
circleci orb info	Displays information about an orb, including its version, description, and usage examples.	Useful for understanding the capabilities of an orb before using it in a configuration.
circleci orb list	Lists all orbs within a specified namespace.	Helps in discovering available orbs and their versions.

Note: Documentation for orbs is hosted on the CircleCI Orb Registry, which provides detailed information about each orb's features and usage.

7. Using Orb Commands

Command	Description	Parameters	Example
orb command	Executes a command defined in an orb	`orb-name/command-name`	`orb command circleci/node@5.0.0/install-node`
orb command --param	Passes parameters to an orb command	`parameter-name=value`	`orb command circleci/node@5.0.0/install-node --param version=18`

Example: Using a command with parameters

orb command circleci/python@2.1.0/run-tests --param python-version=3.9 --param test-args="--verbose"

Note: Commands must be defined within the orb's configuration to be executable.

8. Using Orb Jobs

Property	Description	Example
orb.job	Reference to a job defined in an orb	`orb.job: my-orb/job-name`
orb.job.parameters	Parameters to pass to the orb job	`orb.job: my-orb/job-name<br> parameters:<br> env: production`

Example: Using a job from an orb

version: 2.1
orbs:
  my-orb: circleci/my-orb@1.0.0
jobs:
  build:
    executor: my-orb/executor-name
    steps:
      - my-orb/job-name:
          env: production

Note: Orb jobs can be used in any context where a job is expected, such as within a workflow or as part of a larger configuration.

9. Using Orb Executors

Property	Description	Values
executor	Name of the executor to use	`my-orb/executor-name`
environment	Environment variables to set in the executor	`{ "VAR1": "value1", "VAR2": "value2" }`
resource_class	Resource class to use for the executor	`medium`, `large`, `xlarge`

Example: Using an Orb Executor

version: 2.1
orbs:
  my-orb: my-organization/my-orb@1.0.0
jobs:
  build:
    executor: my-orb/my-executor
    steps:
      - checkout
      - run: echo "Running on custom executor"

Note: Executors defined in orbs must be declared in the orbs section before they can be used.

10. Parameterizing Orb Usage

Parameter	Type	Description	Default
orb-parameter-name	string	Name of the parameter to pass into the orb	None
orb-parameter-value	any	Value to pass into the orb parameter	None

Example: Using Parameters in Orb Configuration

version: 2.1
orbs:
  my-orb: <orb-name>/v1
jobs:
  build:
    parameters:
      env-var:
        type: string
        default: "production"
    executor: my-orb/default-executor
    steps:
      - my-orb/run-tests:
          environment: <<parameters.env-var>>