Search Results for ""

Orbs Introduction

CircleCI orbs are shareable packages of configuration elements, including jobs, commands, and executors. CircleCI provides certified orbs, along with 3rd-party orbs authored by CircleCI partners. It is best practice to first evaluate whether any of these existing orbs will help you in your configuration workflow. Refer to the CircleCI Orbs Registry for the complete list of certified orbs.

Using CircleCI Orbs

If you have chosen to use CircleCI orbs in your workflows and jobs, there are several different ways that you use orbs. You may choose to either import an existing orb (CircleCI and partner-certified orbs) from the CircleCI Orb Registry, or author your own orb for your specific workflow. Each of these approaches is described below.

Importing an Existing Orb

To import an existing orb, perform the steps listed below.

1) Add a single line to to your version 2.1 .circleci/config.yml file for each orb, for example:

version: 2.1

Note: If your project was added to CircleCI prior to 2.1, you must enable “pipelines” to use the orbs key.

2) Add the orbs stanza below your version, invoking the orb. For example:

orbs:
  slack: circleci/slack@0.1.0
  heroku: circleci/heroku@0.0.1

In the above example, the following two orbs are imported into your config:

Importing a Partner Orb

To import a partner orb, perform the steps listed below.

1) Import the orbs key in your .circleci.yml/config.yml file in your configuration.

2) Replace the <orb reference string> value in the example shown below with the orb you wish to import from the CircleCI Orbs Registry. There are a large number of CircleCI-certified and Partner-certified orbs that you may choose from.

version: 2.1

orbs:
  <orb reference string>

Example Partner Orbs from CircleCI Orbs Registry

The table below lists some of the many orbs you may select from the CircleCI Orbs Registry.

Partner Orb Registry Link Orb Reference String
Alcide-io alcide: alcideio/alcide-advisor@1.0.3
Anchore anchore: anchore/anchore-engine@1.0.0
Aqua Security aqua: aquasecurity/microscanner@0.0.1
AWS CLI cli: circleci/aws-cli@0.1.13
AWS Code Deploy codedeploy: circleci/aws-code-deploy@0.0.9
Amazon ECR ecr: circleci/aws-ecr@4.0.1
Amazon ECS ecs: circleci/aws-ecs@0.0.11
Amazon EKS eks: circleci/aws-eks@0.1.0
AWS Parameter Store awsparameter: circleci/aws-parameter-store@1.0.0
AWS S3 s3: circleci/aws-s3@1.0.11
Azure ACR acr: circleci/azure-acr@0.1.1
Azure AKS aks: circleci/azure-aks@0.1.0
Azure CLI cli: circleci/azure-cli@1.1.0
Codecov codecov: codecov/codecov@1.0.1
CodeScene codescene: empear/codescene-ci-cd@1.0.0
Contrast Security contrastsecurity: contrastsecurity/verify@0.1.2
Convox convox: convox/orb@1.4.1
CryptoMove cryptomove: cryptomove/cryptomove@0.0.2
Cypress-io cypress-io: cypress-io/cypress@1.0.0
Datree datree: datree/policy@1.0.6
DeployHub deployhub: deployhub/deployhub-orb@1.2.0
Docker Hub dockerhub: circleci/docker@0.1.0
Fortanix fortanix: fortanix/sdkms-cli@1.0.0
Fossa fossa: fossa/cli@0.0.3
Ghost Inspector ghostinspector: ghostinspector/test-runner@1.0.0
GCP Bin Auth gcp: circleci/gcp-binary-authorization@0.5.2
Google Cloud CLI gcpcli: circleci/gcp-cli@1.8.2
Google Container Registry gcr: circleci/gcp-gcr@0.0.7
Google Kubernetes Engine gke: circleci/gcp-gke@0.1.0
Happo happo: happo/happo@1.0.1
Helm helm: circleci/helm@0.1.1
Honeybadger-io honeybadger-io: honeybadger-io/deploy@1.1.1
Honeycomb buildevents: honeycombio/buildevents@0.1.1
JFrog jfrog: circleci/artifactory@1.0.0
Kublr kublr: kublr/kublr-api@0.0.1
LambdaTest lambdatest: lambdatest/lambda-tunnel@0.0.1
LaunchDarkly launchdarkly: launchdarkly/ld-find-code-refs@1.2.0
LogDNA logdna: logdna/logdna@0.0.1
NeuVector neuvector: neuvector/neuvector-orb@1.0.0
Nirmata nirmata: nirmata/nirmata@1.1.0
Nowsecure nowsecure: nowsecure/ci-auto-orb@1.0.5
Oxygen oxygen: cloudbeat/oxygen@1.0.0
Packagecloud packagecloud: packagecloud/packagecloud@0.1.0
Pantheon pantheon: pantheon-systems/pantheon@0.1.0
Percy percy: percy/agent@0.1.2
Postman postman: postman/newman@0.0.1
Probely probely: probely/security-scan@1.0.0
Provar provar: provartesting/provar@1.9.10
Pulumi pulumi: pulumi/pulumi@1.0.0
realMethods realmethods: realmethods/appgen@1.0.1
Red Hat OpenShift redhat: circleci/redhat-openshift@0.1.0
Rocro rocro: rocro/inspecode@1.0.0
Rollbar rollbar: rollbar/deploy@1.0.0
Rookout rookout: rookout/rookout-node@0.0.2
Sauce Labs saucelabs: saucelabs/sauce-connect@1.0.1
Snyk snyk: snyk/snyk@0.0.8
Sonatype sonatype: sonatype/nexus-platform-orb@1.0.2
Styra styra: styra/cli@0.0.7
Testim testim: testimio/runner@1.1.1
Twistlock twistlock: twistlock/twistcli-scan@1.0.4
Unmock unmock: unmock/unmock@0.0.7
VMware Code Stream vmware/codestream@1.0.0
WhiteSource whitesource: whitesource/whitesource-scan@18.10.2
WhiteSource Vulnerability Checker whitesource: whitesource/vulnerability-checker@19.7.2
xMatters xmatters: xmatters/xmatters-orb@0.0.1

Note: As a prerequisite, you must enable use of 3rd-party orbs on the Settings > Security page for your org.

Authoring Your Own Orb

If you find that there are no existing orbs that meet your needs, you may author your own orb to meet your specific environment or configuration requirements by using the CircleCI CLI as shown in the circleci orb help output below. Although this is more time-consuming than using the import feature, authoring your own orb enables you to create a world-readable orb for sharing your configuration. See Creating Orbs for more information.

$ circleci orb help
Operate on orbs

Usage:
  circleci orb [command]

Available Commands:
  create      Create an orb in the specified namespace
  list        List orbs
  process     Validate an orb and print its form after all pre-registration processing
  publish     Publish an orb to the registry
  source      Show the source of an orb
  validate    Validate an orb.yml

Note When authoring an orb, you will agree to CircleCI’s Code Sharing Terms of Service when your organization opts-in to 3rd party orb use and authoring. CircleCI thereby licenses all orbs back to users under the MIT License agreement.

See Also

  • Refer to Orbs Concepts for high-level information about CircleCI orbs.
  • Refer to Orbs FAQ for information on known issues and questions that have been addressed when using CircleCI orbs.
  • Refer to Orbs Reference for examples of reusable orbs, commands, parameters, and executors.
  • Refer to Orb Testing Methodologies for information on how to test orbs you have created.
  • Refer to Orbs Publishing Process for information about orbs that you may use in your workflows and jobs.
  • Refer to Configuration Cookbook for information about how you can use CircleCI orb recipes in your configurations.