Orbs, Jobs, Steps, and Workflows
The document provides an overview of orbs, jobs, steps and workflows.
- Orbs overview
- Jobs overview
- Steps overview
- Sample configuration with imported orb
- Sample configuration with concurrent jobs
- See also
Orbs are packages of config that you either import by name or configure inline to simplify your config, share, and reuse config within and across projects. See Orbs Concepts for details about how to use orbs in your config and an introduction to orb design. Visit the Orbs Registry to search for orbs to help simplify your config.
Jobs are collections of steps. All of the steps in the job are executed in a single unit, either within a fresh container or VM.
The following diagram illustrates how data flows between jobs:
- Workspaces persist data between jobs in a single workflow.
- Caching persists data between the same job in different workflows runs.
- Artifacts persist data after a workflow has finished.
Jobs can be run using the
machine (linux), macOS or Windows executors, or the
docker executor, which can compose Docker containers to run your jobs and any services they require, such as databases.
When using the
docker executor the container images listed under the
docker: keys specify the containers to start. Any public Docker images can be used with the
See the Choosing an Executor Type document for use cases and comparisons of the different executor types.
Steps are a collection of executable commands which are run during a job, the
checkout: key is required to checkout your code and a key for
run: enables addition of arbitrary, multi-line shell command scripting. In addition to the
run: key, keys for
add_ssh_keys are nested under Steps.
Sample configuration with imported orb
Find full details of the AWS S3 orb in the CircleCI Orbs Registry.
version: 2.1 orbs: aws-s3: email@example.com #imports the s3 orb in the circleci namespace # x.y.z should be replaced with the orb version you wish to use jobs: deploy2s3: docker: - image: cimg/<language>:<version TAG> auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - aws-s3/sync: #invokes the sync command declared in the s3 orb from: . to: "s3://mybucket_uri" overwrite: true workflows: build-test-deploy: jobs: - deploy2s3
Sample configuration with concurrent jobs
Following is a sample 2.0
version: 2 jobs: build: docker: - image: cimg/<language>:<version TAG> auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - run: <command> test: docker: - image: cimg/<language>:<version TAG> auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference steps: - checkout - run: <command> workflows: version: 2 build_and_test: jobs: - build - test
This example shows a concurrent job workflow where the
test jobs run concurrently to save time. Refer to the Workflows document for complete details about orchestrating job runs with concurrent, sequential, and manual approval workflows.
Help make this document better
This guide, as well as the rest of our docs, are open-source and available on GitHub. We welcome your contributions.
- Suggest an edit to this page (please read the contributing guide first).
- To report a problem in the documentation, or to submit feedback and comments, please open an issue on GitHub.
- CircleCI is always seeking ways to improve your experience with our platform. If you would like to share feedback, please join our research community.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.