# Orbs concepts CircleCI orbs are shareable packages of configuration elements, including the following: * [Jobs](https://circleci.com/docs/reference/reusing-config/#authoring-parameterized-jobs). A CircleCI job is a collection of steps that run commands or scripts inside a specified executor (like a Docker container or virtual machine). * [Commands](https://circleci.com/docs/reference/reusing-config/#authoring-reusable-commands). A CircleCI command is a reusable block of configuration that can be called multiple times in your configuration. * [Executors](https://circleci.com/docs/reference/reusing-config/#authoring-reusable-executors). A CircleCI executor is a specified environment in which to run a job. Orbs make writing and customizing CircleCI config simple. The reusable configuration elements used in orbs are explained fully in the [Reusable Configuration Reference](https://circleci.com/docs/reference/reusing-config/). ## Orb types CircleCI supports three types of orbs: **Registry orbs** Registry orbs can be developed using the orb dev kit (there is also a manual process) and published for use by anyone (public) or within your organization (private). Registry orbs follow strict semantic versioning. Public registry orbs are available from the [Orbs Registry](https://circleci.com/developer/orbs). Registry orbs are available for many languages, platforms, services, and tools. Visit the [Orbs Registry](https://circleci.com/developer/orbs) to search for orbs to help simplify your configuration. If you would like to author your own registry orb, read more on the [Create a Registry Orb](https://circleci.com/docs/orbs/author/create-test-and-publish-a-registry-orb/) page. **URL orbs** URL orbs are stored in a publicly accessible location (for example, a git repository or a public S3 object) and are not published to the orbs registry. URL orbs do not follow semantic versioning, and can be accessed directly using an `https` URL. An org-level allow list is used to manage the addresses of URL orbs that can be used in a project in that organization. Organization admins can manage the allow list at **Org**  **Orbs**. See the [Managing URL Orb Allow Lists](https://circleci.com/docs/orbs/use/managing-url-orbs-allow-lists/) guide for more information on scoping allowed URL orbs for your organization. If you would like to author your own URL orb, see the [Create, Test, and Use URL Orbs](https://circleci.com/docs/orbs/author/create-test-and-use-url-orbs/) guide. **Inline orbs** Inline orbs are defined directly within your project’s configuration file. They are project-specific and not published or shared externally. Inline orbs are ideal for reusable configuration within a single project, and are also useful for learning orb concepts and testing configurations prior to extracting to a URL or registry orb. Inline orbs do not require publishing, versioning, or external hosting. They exist only within your `.circleci/config.yml` file. See the [Create an Inline Orb](https://circleci.com/docs/orbs/author/create-an-inline-orb/) guide for more information on creating inline orbs. ## Orb types comparison The following table provides a detailed comparison of the three orb types: Feature Registry Orbs URL Orbs Inline Orbs **Location** Published to Orb Registry, stored in GitHub repository Hosted at accessible URL (GitHub, S3, etc.) Defined in config file **Sharing scope** Public or private across organizations Organization-wide (with allow-list) Project-specific only **Versioning** Semantic versioning Manual (Git branches, tags, commits) None **VCS support** Registry orbs are hosted in GitHub only but can be used by all CircleCI users if public GitHub, Bitbucket GitHub, GitLab, Bitbucket **Mutability** Immutable Mutable Mutable (edit config directly) **Updates** Publish new semantic version (immutable) Update hosted file (5-minute cache) Edit config file directly **Access control** Namespace permissions Organization allow-list Repository access only **Best for** Community sharing, public packages, certified orbs Organization-wide shared config, overriding config, proprietary logic Project-specific reusable config, learning, testing **Choose this type when:** * You want to share your orb with the community. * You want to use semantic versioning for your orb. * You want your orb to be discoverable in the CircleCI Orb Registry. * You want to leverage the orb development kit and automated CI/CD pipeline. * You want to use centralized configuration for your organization. * You need to share configuration within your organization. * You need direct control over updates and distribution. * You need to use proprietary or confidential configurations. * Configuration is specific to a single project. * You want zero publishing or hosting overhead. * You’re learning about orbs and want to experiment. * You need immediate changes without any publishing delay. ## Orb configuration elements CircleCI’s [Reusable Configuration](https://circleci.com/docs/reference/reusing-config/) features allow you to define parameterizable configuration elements and re-use those elements throughout a project config file. ### Commands Commands contain one or more steps in which [Parameters](https://circleci.com/docs/reference/reusing-config/#using-the-parameters-declaration) can be used to modify behavior. Commands are the logic of orbs and are responsible for executing steps such as [Checking Out Code](https://circleci.com/docs/reference/configuration-reference/#checkout), or running shell code, for example, running Bash or CLI tools. For more information see the [Authoring Reusable Commands](https://circleci.com/docs/reference/reusing-config/#authoring-reusable-commands) guide. As an example, the AWS S3 orb includes a _command_ to copy a file or object to a new location: `aws-s3/copy`. If your AWS authentication details are stored as environment variables, the syntax to use this command in your config is simply: ````````` version: 2.1 orbs: aws-s3: circleci/aws-s3@4.1.0 jobs: build: docker: - image: 'cimg/python:3.6' steps: - checkout - run: mkdir bucket && echo "lorem ipsum" > bucket/build_asset.txt # using the aws-s3 orb's "copy" command. - aws-s3/copy: from: bucket/build_asset.txt to: 's3://my-s3-bucket-name' #... workflows , other jobs etc. ````````` See the [AWS-S3 Orb](https://circleci.com/developer/orbs/orb/circleci/aws-s3#commands) page in the registry for more information. ### Executors Executors are parameterized execution environments in which [Jobs](#jobs) can be run. CircleCI provides multiple [executor options](https://circleci.com/docs/reference/configuration-reference/#executor-job): * Docker * macOS * Windows * Machine (Linux VM) Executors defined within orbs can be used to run jobs within your project configuration, or within the jobs defined in the orb. #### Executor definition example **Node-Docker:** ````````` description: > Select the version of NodeJS to use. Uses CircleCI's highly cached convenience images built for CI. docker: - image: 'cimg/node:<>' parameters: tag: default: '13.11' description: > Pick a specific cimg/node image version tag: https://circleci.com/developer/images/image/cimg/node type: string ````````` **Ruby-Docker:** ````````` description: > Select the version of Ruby to use. Uses CircleCI's highly cached convenience images built for CI. Any available tag from this list can be used: https://hub.docker.com/r/cimg/ruby/tags docker: - image: 'cimg/ruby:<< parameters.tag >>' parameters: tag: default: '2.7' description: The `circleci/ruby` Docker image version tag. type: string ````````` In the [Node orb](https://circleci.com/developer/orbs/orb/circleci/node), for example, a parameterized Docker-based executor is provided, through which you can set the Docker tag. This provides a simple way to test applications against any version of Node.js when used with the Node orb’s [test job](https://circleci.com/developer/orbs/orb/circleci/node#usage-run_matrix_testing). For more information, see the guide to [Authoring Reusable Executors](https://circleci.com/docs/reference/reusing-config/#authoring-reusable-executors) and example for the [`executor` parameter type](https://circleci.com/docs/reference/reusing-config/#executor). Also, see the registry page for the [Node Orb](https://circleci.com/developer/orbs/orb/circleci/node#executors-default). ### Jobs [Jobs](https://circleci.com/docs/reference/reusing-config/#authoring-parameterized-jobs) define a collection of [steps](https://circleci.com/docs/reference/configuration-reference/#steps) to be run within a given [executor](#executors), and are orchestrated using [Workflows](https://circleci.com/docs/guides/orchestrate/workflows/). Jobs will also individually return their status via [GitHub Checks](https://circleci.com/docs/guides/integration/enable-checks/). When importing an orb which has jobs, you can reference them directly from your workflows. ````````` version: 2.1 orbs: : /@x.y #orb version workflows: use-orb-job: jobs: - / ````````` See the [Authoring Reusable Jobs](https://circleci.com/docs/reference/reusing-config/#authoring-parameterized-jobs) guide for more information, and the [Using Node Test Job](https://circleci.com/developer/orbs/orb/circleci/node#usage-run_matrix_testing) example in the orb registry. ### Usage examples (registry orbs only) Using the [Orb Development Kit](https://circleci.com/docs/orbs/author/orb-author/#orb-development-kit), adding a new usage example is as simple as creating a new file `name-of-example.yml` within the orb project’s [src/examples](https://github.com/CircleCI-Public/Orb-Template/tree/main/src/examples) directory. Usage examples are not for use in project configuration directly. They are a type of orb metadata to share how a user could best make use of the orb in their configuration. These examples are displayed, for reference purposes, in the [Orb Registry](https://circleci.com/developer/orbs). Below is a sample usage example: Example of a usage example for a registry orb ````````` # Source https://github.com/circleci-public/Orb-Template/blob/main/src/examples/example.yml description: > Sample example description. usage: version: 2.1 orbs: : /@1.2.3 workflows: use-my-orb: jobs: - / ````````` ## Namespaces (registry orbs only) A _namespace_ is a unique identifier claimed by a user or organization to group a set of registry orbs by author. Each user or organization can claim _one_ unique and immutable namespace. Each namespace can contain many uniquely named registry orbs. For example, the `circleci/rails` orb may coexist in the registry with an orb called `/rails` because they are in separate namespaces. Organizations are, by default, limited to claiming only one namespace. This policy is designed to limit name-squatting and namespace noise. If you need to change your namespace, contact [support](https://support.circleci.com/). By default, created namespaces appear as "community" namespaces in the [Orb Registry](https://circleci.com/developer/orbs). ## Semantic versioning (registry orbs only) Registry orbs use the [SemVer](https://semver.org/) release process, in which each orb update follows a standardized versioning pattern that orb authors and users should take advantage of. In Semantic versioning, release versions are represented by three integers separated by a `.`, where each integer represents a different type of change being added. ````````` [Major].[Minor].[Patch] ````````` SemVer Description Major Breaking changes. Minor Backwards compatible additional features. Patch Bug fixes. When you import a registry orb, you can pin it to a particular SemVer component. Imported Version Description 1.2.3 Will match full SemVer version. No changes will be introduced. 1.2 Locked to major version `1`, minor version `2`, will receive all patch updates. 1 Locked to major version `1`. Will receive all minor and patch updates. Major version will not change automatically. volatile **Not Recommended** Will pull the last published version of the orb, may be useful in testing. Not a part of SemVer versioning. To avoid negatively impacting a user’s CI process, orb authors should strictly adhere to SemVer versioning to ensure no breaking changes are introduced at the `minor` or `patch` update levels. CircleCI does not currently support non-numeric semantic versioning elements. We suggest that you use either SemVer-style version strings in x.y.z format, or a development-style version string in dev:\* format. ## Registry orb versions (development vs production) This section applies to **registry orbs only**. Inline orbs and URL orbs do not use the registry orb versioning system. Registry orbs can be published in two states: * Production (immutable, semantic versioned). * Development (mutable, temporary). ### Production registry orbs Production registry orbs are immutable and can be found on the [Orb Registry](https://circleci.com/developer/orbs). Production registry orbs: * Are immutable—they cannot be deleted or edited, and updates must be provided in a new SemVer release. * Have a version string in SemVer format, for example, `/@1.2.3`. * Can only be published by an owner of the namespace organization. * Are published to the [CircleCI Orb Registry](https://circleci.com/developer/orbs). * Are open source, released under [MIT license](https://circleci.com/developer/orbs/licensing). * Are available via CircleCI CLI. ### Development registry orbs Development registry orbs are temporary, mutable orb tag versions, useful for rapid development and testing prior to deploying a production release. Development registry orbs: * Can only be published if the orb has an initial production version. * Are mutable, can be overwritten, and automatically expire 90 days after publication. * Have a version string beginning with `dev:` followed by any string, for example, `/@dev:my-feature-branch`. * Can be published by any member of the namespace organization. * Are open source, released under the [MIT license](https://circleci.com/developer/orbs/licensing). * Are available via the CircleCI CLI if the development tag name is known. ## Private registry orbs vs. public registry orbs This section applies to **registry orbs only**. Inline orbs are inherently private to the project. URL orbs are controlled by your organization’s allow-list and hosting access. Registry orbs can be published as public or private: * If you prefer to publish your registry orb so that only those within your organization can see and use it, you should publish a **private registry orb**. * If you want to publish your registry orb to the [CircleCI Orb Registry](https://circleci.com/developer/orbs) for use by anyone, create a **public registry orb**. Private registry orbs are described in more detail below. ### Private registry orbs An unlimited amount of private registry orbs are available on all of CircleCI’s [plans](https://circleci.com/pricing). Using a private registry orb enables you to author an orb while ensuring the following: * Your orb will not appear in the [CircleCI Orb Registry](https://circleci.com/developer/orbs) unless you have the direct URL and are authenticated with the org that created it. * Your orb cannot be viewed or used by someone outside of your organization. * Your orb cannot be used in a pipeline that does not belong to your organization. By choosing to use a private registry orb instead of a public registry orb, you also need to understand certain inherent limitations, which include: * You will be unable to use the `circleci config validate` command to validate your configuration. You may, however, use one of the following options: * Paste the content of the orb into the `orbs` stanza of your configuration. * Use the `circleci config validate --org-id ` command to validate your configuration. * You cannot use private registry orbs from one organization in another organization’s pipelines, regardless of the relationship between organizations. This means that even if you commit code and start a pipeline, and have the necessary membership in both organizations, you can use a private registry orb from your configuration file, but not from another orb. ### Authoring registry orbs Both public and private registry orbs can be authored in two ways: * Using the [Manual Orb Authoring Process](https://circleci.com/docs/orbs/author/manual-orb-authoring-process/). * Using the [Orb Development Kit](https://circleci.com/docs/orbs/author/orb-author/#orb-development-kit) (recommended). For authoring URL orbs, see [Create, Test, and Use URL Orbs](https://circleci.com/docs/orbs/author/create-test-and-use-url-orbs/). For authoring inline orbs, see [Create an Inline Orb](https://circleci.com/docs/orbs/author/create-an-inline-orb/). ## Orb packing (registry orbs only) Registry orbs are singular YAML files, typically named `orb.yml`. However, for development, it is often easier to break the code up into more manageable chunks. The `circleci orb pack` command, a component of the [Orb Development Kit](https://circleci.com/docs/orbs/author/orb-author/#orb-development-kit), is used to "pack" or condense the separate YAML files together. If you are using the orb development kit, orb packing is handled automatically by the included CI/CD pipeline, with the [orb-tools/pack](https://circleci.com/developer/orbs/orb/circleci/orb-tools#jobs-pack) job. Orb Project Structure type name Directory [commands](https://github.com/CircleCI-Public/Orb-Template/tree/main/src/commands) Directory [examples](https://github.com/CircleCI-Public/Orb-Template/tree/main/src/examples) Directory [executors](https://github.com/CircleCI-Public/Orb-Template/tree/main/src/executors) Directory [jobs](https://github.com/CircleCI-Public/Orb-Template/tree/main/src/jobs) File [@orb.yml](https://github.com/CircleCI-Public/Orb-Template/blob/main/src/%40orb.yml) In order to _pack_ an orb, an `@orb.yml` file must be present. The `@` signifies the _root_ of our orb project. See the [Create, Test, and Publish a Registry Orb](https://circleci.com/docs/orbs/author/create-test-and-publish-a-registry-orb/#orbyml) guide for more information. Within the same directory, you can include additional directories for each orb component’s type, such as: * [Reusable Commands](https://circleci.com/docs/reference/reusing-config/#authoring-reusable-commands). * [Parameterized Jobs](https://circleci.com/docs/reference/reusing-config/#authoring-parameterized-jobs). * [Reusable Executors](https://circleci.com/docs/reference/reusing-config/#authoring-reusable-executors). * [Usage Examples](#usage-examples). Any additional files or folders will be safely ignored. Additionally, the _pack_ command provides a special pre-processor for orb developers that allows you to import code from external files using the [File include syntax](#file-include-syntax) (`<>`). ### CLI command ````````` circleci orb pack > orb.yml ````````` For orb development kit users, this step is handled automatically. ## File include syntax The `<>` syntax is a special key for use with the [`circleci orb pack` command](#orb-packing) and _will not_ work more widely on CircleCI. The file include syntax (`<>`) is a special config enhancement. It allows you to import the contents of a file in place as the value for any key within a CircleCI orb configuration file. When `circleci orb pack > orb.yml` is run against a directory containing an `@orb.yml` file, the pack command begins to combine the contents of the files into a single `orb.yml` file. During the packing process, each instance of the `<>` value will be replaced by the contents of the file referenced within. Included files are always referenced from the relative location of the `@orb.yml` file. **Command-YAML:** ````````` description: A simple command that imports from a file when packed. steps: - run: name: Hello Greeting command: <> ````````` **file-sh:** ````````` # This is a bash file, but could really be any text-based file echo "Hello World" ````````` **Packed Command-YAML:** ````````` description: A simple command that imports from a file when packed. steps: - run: name: Hello Greeting command: | # This is a bash file, but could really be any text-based file echo "Hello World" ````````` File inclusion is especially useful for separating your configuration’s Bash logic from your YAML. Including Bash scripts will allow you to develop and test your Bash outside of your orb. View more about including Bash scripts in the [Orb Author](https://circleci.com/docs/orbs/author/create-test-and-publish-a-registry-orb/#scripts) guide. ## Using orbs within your orb and register-time resolution An orbs stanza can be used inside an orb. Because production orb releases are immutable, the system will resolve all orb dependencies at the time you register your orb rather than at the time you run your build. For example, orb `foo/bar` is published at version 1.2.3 with an orbs stanza that imports `biz/baz@volatile`. At the time you register `foo/bar@1.2.3` the system will resolve `biz/baz@volatile` as the latest version and include its elements directly into the packaged version of `foo/bar@1.2.3`. If `biz/baz` is updated to `3.0.0`, anyone using `foo/bar@1.2.3` will not see the change from `biz/baz@3.0.0` until `foo/bar` is published at a higher version than `1.2.3`. Orb elements may be composed directly with elements of other orbs. For example, you may have an orb that looks like the example below. ````````` version: 2.1 orbs: some-orb: some-ns/some-orb@volatile executors: my-executor: some-orb/their-executor commands: my-command: some-orb/their-command jobs: my-job: some-orb/their-job another-job: executor: my-executor steps: - my-command: param1: "hello" ````````` ## See also * Refer to [Orb Introduction](https://circleci.com/docs/orbs/use/orb-intro/) for a high-level overview of CircleCI orbs. * Refer to [Introduction to Authoring Orbs](https://circleci.com/docs/orbs/author/orb-author/) for creating registry orbs. * Refer to [Orbs FAQs](https://circleci.com/docs/orbs/use/orbs-faq/) for information on frequent issues encountered when using orbs.