> For the complete documentation index, see [llms.txt](https://circleci.com/docs/llms.txt)

# Jobs and steps

This page provides an overview of CircleCI jobs and steps.

## Jobs overview

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](https://circleci.com/docs/guides/orchestrate/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 workflow runs.
    
*   Artifacts persist data after a workflow has finished.
    

Figure 1. Jobs overview

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](https://circleci.com/developer/images).

See the [Introduction to Execution Environments](https://circleci.com/docs/guides/execution-managed/executor-intro/) document for a comparison of the different executor types, and links to further information for each option.

### Job naming

When you configure a job you will give it a name. This name is its job property name:

`````````
version: 2.1

jobs:
  my-job: # the job property name
`````````

The job property name can be anything you like with the following restrictions:

*   Must be unique within the `jobs` stanza.
    
*   Only ASCII alphabet characters, underscores, and dashes.
    
*   No spaces.
    

When you configure a job in a workflow you have the option to give it an alternative name (See the [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/#name) page for more information). This alternative name can be useful if you want to call a job more than once in a workflow.

`````````
workflows:
  jobs:
    my-job: # the job property name
      name: My Job # the alternative job name within the workflow
`````````

The job name within the workflow can be anything you like _including_ spaces and special characters.

### Job types

A job can be one of four types:

*   `release`: Jobs with this type are used to connect your pipeline configuration to a deployment in the CircleCI deploys UI.
    
*   `approval`: This type is used to configure a manual approval step.
    
*   `no-op`: This type is used to configure a job that performs no actions and consumes no credits.
    
*   `build`: This is the default type used to build your code.
    

You can set the type of a job by adding the `type` key to the job configuration.

See the [Configuration Reference](https://circleci.com/docs/reference/configuration-reference/#job-type) page for more information on how to use the different job types.

### Job status transitions

The following diagram and table shows the possible job statuses and transitions.

`````````mermaid
stateDiagram-v2
    direction TB
    [*] --> blocked

    state "blocked or not running" as pending
    blocked --> pending : Job instructed to start but not yet started
    blocked --> unauthorized : Trying to use a context without permission
    blocked --> not_run : Job's dependencies will never be satisfied

    pending --> running

    pending --> blocked : Rerun

    running --> canceled
    pending --> canceled
    blocked --> canceled

    pending --> failed : Abusive / Sanctioned
    running --> failed
    running --> success

    failed --> [*]
    success --> [*]
    canceled --> [*]
    unauthorized --> [*]
    not_run --> [*]
`````````

Figure 2. CircleCI Cloud job status transitions

`````````mermaid
stateDiagram-v2
    direction TB
    [*] --> blocked

    state "blocked or not running" as pending
    blocked --> pending : Job instructed to start but not yet started
    blocked --> unauthorized : Trying to use a context without permission

    pending --> running

    pending --> not_run : Only build PRs setting enabled
    pending --> blocked : Rerun

    running --> canceled
    pending --> canceled
    blocked --> canceled

    pending --> failed : Abusive / Sanctioned
    running --> failed
    running --> success

    not_run --> [*]
    success --> [*]
    failed --> [*]
    canceled --> [*]
    unauthorized --> [*]
`````````

Figure 3. CircleCI Server job status transitions

 

Status

Description

Blocked/Not Running

All jobs start off in a blocked state. Jobs called `build` move on to a Not Running state before starting.

Running

Job is running.

On Hold

The job is running but requires manual approval.

Not Run

The job is skipped.

Success

The job succeeded.

Failed

The job failed or terminated for unknown reasons.

Canceled

The job was canceled. An actor might cancel a job, or cancel a workflow. A job may be canceled due to auto-cancellation. Support engineers can force cancellation of a job.

Unauthorized

The job uses a restricted context and the actor that triggered the work does NOT have access to that context.

## Steps overview

Steps are collections of executable commands, which are run during a job.

The `checkout` key is required under `steps` to check out your code. The `run` key enables the addition of arbitrary, multi-line shell command scripting.

In addition to the `run` key, the following keys are nested under steps:

*   `save_cache`
    
*   `restore_cache`
    
*   `store_artifacts`
    
*   `store_test_results`
    
*   `add_ssh_keys`
    

For a full list of step options see the [Steps Key](https://circleci.com/docs/reference/configuration-reference/#steps) section of the Configuration Reference.

## Access jobs and steps in the CircleCI app

A pipeline is composed of workflows, which are composed of jobs. By navigating from a pipeline to a specific job, you can access your job output, timing information, test results, artifacts and resource usage information through several tabs (1).

The output of each job can be opened in a new tab (in either raw or formatted styling) with a unique link, making it shareable between team members. You can also use the search functionality to find specific lines of output (2).

Figure 4. Job tab options in the CircleCI web app

## 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](https://circleci.com/docs/reference/configuration-reference/#matrix). Below is a basic example of passing a parameter to a job when it is run.

**Using Docker?** Authenticating Docker pulls from image registries is recommended when using the Docker execution environment. Authenticated pulls allow access to private Docker images, and may also grant higher rate limits, depending on your registry provider. For further information see [Using Docker authenticated pulls](https://circleci.com/docs/guides/execution-managed/private-images/).

`````````
version: 2.1
​
jobs:
  print-a-message:
    docker:
      - image: cimg/base:2022.03
    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](https://circleci.com/developer/orbs/orb/circleci/slack) as an example. This orb provides a job called [`on-hold`](https://circleci.com/developer/orbs/orb/circleci/slack#usage-on_hold_notification), 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: circleci/slack@4.1

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](https://circleci.com/developer/orbs/orb/circleci/slack) 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):

This example also uses the [Node orb](https://circleci.com/developer/orbs/orb/circleci/node).

`````````
version: 2.1

orbs:
  node: 'circleci/node:4.1'
  slack: circleci/slack@4.1

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
`````````

## Next steps

*   Read more about orchestrating jobs in the [Using Workflows to Schedule Jobs](https://circleci.com/docs/guides/orchestrate/workflows/) page.
    
*   Read more about passing data between jobs in the [Using Workspaces to Share Data Between Jobs](https://circleci.com/docs/guides/orchestrate/workspaces/) page.