Jobs and Steps
The document provides an overview of CircleCI jobs and steps.
A CircleCI job is a collection of steps. All of the steps in the job are executed in a single unit, either within a fresh container, or a virtual machine. Jobs are orchestrated using workflows.
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 in Docker containers, using the Docker executor, or in virtual machines using the
machine executor, with Linux, macOS, or Windows images. Secondary containers or VMs can be configured to attach services, such as databases, to run alongside your jobs.
When using the Docker executor, images listed under the
docker key specify the containers you want to start for your job. Any public Docker images can be used with the Docker executor, but CircleCI provides convenience images for a variety of use-cases. Full lists of available convenience and VM images are available in the CircleCI Developer Hub.
See the Introduction to Execution Environments document for a comparison of the different executor types, and links to further information for each option.
Steps are collections of executable commands, which are run during a job.
checkout key is required under
steps to checkout your code. The
run key enables addition of arbitrary, multi-line shell command scripting.
In addition to the
run key, keys for
add_ssh_keys are nested under Steps. For a full list of step options see the Steps key section of the Configuration Reference.
Passing parameters to jobs
Using parameters allows you to run a single job multiple times for different scenarios, such as different package versions or execution environments. An extension of this functionality is matrix jobs. Below is a basic example of passing a parameter to a job when it is run.
version: 2.1 jobs: print-a-message: docker: - image: cimg/base:2022.03 auth: username: mydockerhub-user password: $DOCKERHUB_PASSWORD # context / project UI env-var reference parameters: message: type: string steps: - run: echo << parameters.message >> workflows: my-workflow: jobs: - print-a-message: message: Hello!
Using a job from an orb
Orbs are packages or reusable configuration that you can use in your projects. Orbs usually contain commands that you can use in your jobs, as well as whole jobs that you can schedule in your workflows.
Take the Slack orb as an example. This orb provides a job called
on-hold, which you can use in your workflows. This job pauses the workflow to require manual approval, and sends a slack notification. To use this job, reference it in your workflow (see line 10):
version: 2.1 orbs: slack: firstname.lastname@example.org workflows: on-hold-example: jobs: - my_test_job - slack/on-hold: context: slack-secrets requires: - my_test_job - pause_workflow: requires: - my_test_job - slack/on-hold type: approval - my_deploy_job: requires: - pause_workflow
Using a command from an orb in a job
Using the Slack orb as an example again, this orb includes a command called
notify, which is used to notify a specified slack channel. You can reference this command in your job as follows (see line 16):
version: 2.1 orbs: node: 'circleci/node:4.1' slack: email@example.com jobs: deploy: executor: name: node/default steps: - checkout - node/install-packages - run: command: npm run deploy - slack/notify: channel: ABCXYZ event: fail template: basic_fail_1 workflows: deploy_and_notify: jobs: - deploy: context: slack-secrets
- Read more about orchestrating jobs in the Using Workflows to Schedule Jobs page.
- Read more about passing data between jobs in the Using Workspaces to Share Data between Jobs page.
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.
Our support engineers are available to help with service issues, billing, or account related questions, and can help troubleshoot build configurations. Contact our support engineers by opening a ticket.
You can also visit our support site to find support articles, community forums, and training resources.
CircleCI Documentation by CircleCI is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.