Creating Custom Orbs

1. Initializing Orb Project

Step	Description	Action
1	Set up local development environment	Install CircleCI CLI and configure your project directory.
2	Create orb directory structure	Use the command `circleci orb init` to scaffold the project.
3	Define orb metadata	Create `orb.yml` with name, version, and description.
4	Implement orb logic	Add configuration files like `.circleci/config.yml` with jobs and steps.

Example: Initialize Orb Project

circleci orb init my-orb --name circleci/my-orb

Note: Ensure that your project is initialized with a CircleCI config file before running the orb init command.

2. Defining Orb Commands

Property	Description	Values	Notes
name	Unique identifier for the command	`string`	Required field
parameters	Optional input parameters for the command	`object`	Each parameter has `type`, `default`, and `description`
steps	Sequence of steps to execute when command is invoked	`array`	Must contain valid CircleCI steps

Example: Basic Orb Command Definition

version: 2.1
commands:
  setup-node:
    parameters:
      node-version:
        type: string
        default: "18"
    steps:
      - checkout
      - run:
          name: "Setup Node.js"
          command: "node --version"

Example: Command with Parameters

version: 2.1
commands:
  deploy-to-heroku:
    parameters:
      app-name:
        type: string
        default: "my-app"
      env:
        type: string
        default: "production"
    steps:
      - run:
          name: "Deploy to Heroku"
          command: "heroku deploy --app ${{ parameters.app-name }} --env ${{ parameters.env }}"

3. Creating Orb Jobs

Property	Description	Values
name	Unique identifier for the job	`string`
steps	Sequence of commands or actions to execute	`list`
executor	Executor to use for running the job	`string`
parameters	Input parameters for the job	`map`

Example: Basic Orb Job

jobs:
  build-and-test:
    steps:
      - checkout
      - run:
          name: Run tests
          command: npm test

Example: Orb Job with Parameters

jobs:
  deploy-to-env:
    parameters:
      environment:
        type: string
        default: production
    steps:
      - run:
          name: Deploy to << parameters.environment >>
          command: |
            echo "Deploying to << parameters.environment >>"

4. Defining Orb Executors

Property	Description	Values
executors	Defines reusable execution environments	`name` (string), `docker` (array), `machine` (object), `resource_class` (string)

Example: Basic Executor Definition

executors:
  my-executor:
    docker:
      - image: circleci/node:16

Example: Machine Executor

executors:
  machine-executor:
    machine:
      image: ubuntu-2004:2023.07.1

Example: Resource Class Executor

executors:
  resource-executor:
    resource_class: large
    docker:
      - image: circleci/python:3.9

5. Adding Orb Parameters

Parameter	Type	Description	Default
name	`string`	Name of the parameter	`null`
type	`string`	Type of the parameter (e.g., `string`, `boolean`, `integer`)	`string`
description	`string`	Description of the parameter's purpose	`""`
default	`any`	Default value if not provided	`null`
required	`boolean`	Whether the parameter is required	`false`

Example: Defining Parameters in an Orb

parameters:
  project-name:
    type: string
    description: "Name of the project to build"
    default: "my-app"
  debug-mode:
    type: boolean
    description: "Enable debug mode"
    default: false

6. Using Parameter Types

Parameter Type	Description	Example	Notes
string	Text value, default is empty string	`name: string`	Most common type for text inputs
boolean	True or false value	`debug: boolean`	Used for enabling/disabling features
integer	Whole number value	`timeout: integer`	Useful for time limits and counts
float	Decimal number value	`ratio: float`	For precise numeric values
enum	One of a predefined list of values	`environment: enum`	Useful for selecting from a set of options
array	List of values, all of same type	`files: array`	Can be of any type (string, integer, etc.)
object	Structured data with key-value pairs	`config: object`	Allows complex nested parameter structures

Example: Using Parameter Types in an Orb

parameters:
  project-name:
    type: string
    description: "Name of the project"
    default: "my-app"
  debug-mode:
    type: boolean
    description: "Enable debug logging"
    default: false
  timeout-seconds:
    type: integer
    description: "Timeout in seconds"
    default: 30
  environment:
    type: enum
    description: "Environment to deploy to"
    enum: [staging, production]
    default: staging
  files-to-upload:
    type: array
    description: "List of files to upload"
    default: []
  config:
    type: object
    description: "Configuration object"
    default: {}

7. Testing Orbs Locally

Testing orbs locally ensures they function as expected before publishing. CircleCI provides the circleci CLI tool to validate and test orbs in a local environment.

Command	Description	Example
circleci orb validate	Validates the syntax and structure of an orb configuration file.	`circleci orb validate src/orb.yml`
circleci orb publish	Publishes an orb to the CircleCI registry (requires valid configuration and permissions).	`circleci orb publish src/orb.yml my-org/my-orb@1.0.0`
circleci local execute	Executes a job or workflow locally using the orb configuration.	`circleci local execute -c config.yml -o my-org/my-orb@1.0.0`

Example: Validating an Orb Configuration

circleci orb validate src/orb.yml

Example: Executing a Local Job Using an Orb

circleci local execute -c config.yml -o my-org/my-orb@1.0.0

Note: Ensure that the circleci CLI is installed and configured with appropriate credentials to test orbs locally.

Warning: Local execution does not replicate the full CircleCI environment, so some features or behaviors may differ from actual job execution.

8. Using Development Versions

When developing custom orbs, you may want to test changes before publishing a new version. CircleCI supports using development versions of orbs directly from your repository.

Orb Reference	Description	Usage
circleci/orb-tools@dev:latest	Development version of orb-tools for testing new features	Use this reference to test changes in your orb development workflow.

Example: Using Development Orb in Config

version: 2.1
orbs:
  myorb: <user>/myorb@dev:latest
workflows:
  test-workflow:
    jobs:
      - myorb/test-job

Note: Development versions are not guaranteed to be stable and may change without notice. Use only for testing purposes.

9. Publishing Orbs

Field	Description	Example
orbs	Defines the orbs used in the configuration	`orbs: my-orb: my-org/my-orb@1.0.0`
version	Version of the orb to use	`my-orb@1.2.3`
description	Short description of the orb's purpose	`Description: "A set of useful tools for CI"`

Example: Publishing an Orb

version: 2.1
orbs:
  my-orb: my-org/my-orb@1.0.0

workflows:
  build:
    jobs:
      - my-orb/my-job

Note: Orbs must be published to the CircleCI registry before they can be used in configurations.

Warning: Ensure that the orb's version is compatible with your CircleCI configuration.

Steps to Publish an Orb

Create a valid orb configuration file
Validate the orb using circleci orb validate
Publish the orb using circleci orb publish
Update your configuration to use the published orb

10. Versioning Orbs

Version Format	Description	Notes
major.minor.patch	Standard semantic versioning format	Used for stable releases
major.minor.patch-prerelease	Pre-release versions with suffixes like -alpha, -beta, -rc	Used for development builds
major.minor.patch+build	Build metadata with + suffix	Not used for versioning logic but can be included

Example: Orb Version in config.yml

orbs:
  my-orb: my-org/my-orb@2.1.0

Note: CircleCI uses semantic versioning to manage orb updates. When you specify a version, CircleCI will pull the exact version or the latest compatible version if no patch is specified.

Warning: Avoid using latest in production workflows as it can introduce breaking changes without notice.

Version Tag	Behavior	Use Case
@1.2.3	Pins to exact version	Production environments
@1.2	Allows patch updates	Stable environments with minor updates
@1	Allows minor and patch updates	Development environments
@latest	Uses the latest version	Testing or development only

11. Managing Orb Namespaces

Property	Description	Notes
namespace.name	Name of the namespace	Must be unique across CircleCI
namespace.owner	Owner of the namespace	Can be a user or organization

Example: Creating a Namespace

circleci namespace create <namespace-name> <owner>

Note: Namespaces are used to organize orbs and provide a way to group related orbs under a common name.