---
metadata:
  - name: generator
    content: Diplodoc Platform v5.54.2
alternate:
  - https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md
  - https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/cubes.md
  - href: en/sourcecraft/ci-cd-ref/cubes.md
    type: text/markdown
    title: Markdown version
  - href: ../../llms.txt
    type: text/markdown
    title: llms.txt
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/en/llms.txt

# Cubes

<!-- source: en/_includes/sourcecraft/ci-cd/cubes-description.md -->
The `cubes` section lists the minimum logical actions, i.e., _cubes_, to execute within a [task](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#tasks).

Such a minimum action may be calling a script, starting a Docker container, or calling a script in a Docker container.

The following cube types are available:

* _Native_: Runs directly on a [worker](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md). 

  If a native cube, while running, changes the worker environment, such as installs a package, creates or deletes a file, etc., such environment will still be there for all other cubes running within a single task.

* _Docker cube_: Runs within a Docker container started on a worker. Technically, it runs a custom script or a container script, if the container has an entry point.

  If a Docker cube, while running, changes the environment, such environment will be available to other cubes within the task only in case the changes were made within the `/sourcecraft` directory. All other changes will be removed along with the Docker container.

  When working from a container, the directories are mounted as follows:
  * The directory housing files associated with the task in progress is mounted to `/sourcecraft`.
  * The directory to clone the repository to and that is also the working directory (`workdir`) by default, is mounted to `/sourcecraft/workspace`.

  You can get the paths of these directories from the `$SOURCECRAFT_ROOT_DIRECTORY` and `$SOURCECRAFT_WORKSPACE` [predefined environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/predefined-variables.md), respectively.

  To configure a Docker cube, use the [image](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md#image) property to specify the Docker image name and, optionally, username, password, entry point, and arguments.

* _Devcontainer cube_: Runs in the environment defined in the [Development Container specification](https://containers.dev/implementors/spec/). This cube builds a container from the configuration in the repository and runs a custom script in that container.

  A `devcontainer` cube is specified in the [devcontainer](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/cubes.md#devcontainer) property which contains the path to the directory with the `devcontainer.json` or `Dockerfile` specification. 
  
  [Sample Development Container specifications](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/spaces-env-config.md#examples)

In cubes, you can use [environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#variables) and [secrets](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#secrets). To provide environment variables from a certain cube to others as `KEY=VALUE` pairs, you can use the `$SOURCECRAFT_ENV` [predefined variable](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/predefined-variables.md).

By default, cubes within a single task are run one by one. To link cubes, use the `needs` property, where you can specify the list of cubes to execute before the current one. If you skip this property, the cube will depend on the one defined immediately before it.

The artifacts that may be created after the cube is run are saved for further use. They will be available for download from the cube in the ![image](../../_assets/console-icons/arrows-3-rotate-right.svg) **CI/CD** section of the repository for 14 days.
<!-- endsource: en/_includes/sourcecraft/ci-cd/cubes-description.md -->

Supported properties:
* `action`: GitHub Action name and version, e.g., `docker/setup-buildx-action@v3.11.1`. For more information, see [Integration with GitHub Actions in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/gh-actions.md).
* `allow_failure`: Flag to control your CI/CD process behavior when errors occur in individual cubes. If `true`, the task will continue as if the cube has completed successfully, even if there is an error. The default value is `false`. For more information, see [Example of a configuration where the task continues despite cube failures](#cubes-with-allow-failure).
* `artifacts`: List of paths to the files that will be created after the cube is run and saved for further use. The artifacts will be available for download from the cube in the ![image](../../_assets/console-icons/arrows-3-rotate-right.svg) **CI/CD** section of the repository for 14 days. For more information, see [Example of a cube configuration using artifacts](#cubes-with-artifacts).
* `env`: [Environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md#variables) that are only available in a specific cube. For more information, see [Example of a cube configuration using variables, including predefined ones](#cubes-with-vars).

  {% note tip %}

  You can also set environment variables within the following sections:
  * [workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md): Variables will be available to all cubes of all tasks within a specific workflow.
  * [tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md): Variables will be available in all cubes of a certain task.

  {% endnote %}

* `exported`: Set this flag to `true` to allow reusing the cube in another repository. The default value is `false`. For more information, see [Example of reusing cube parameters from a YAML file in another repository](#cubes-uses-repo-file).
* `gitlab_workflow`: Path to the GitLab pipeline configuration file. For more information, see [GitLab pipelines in the SourceCraft CI/CD](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/gl-pipelines.md).
* `if`: Cube execution condition. If the condition is not met, the cube is skipped and the job continues. Supports the following operators:
  * `always()`: Execute the cube regardless of whether or not the previous cubes were executed successfully, e.g., if you need to clean the environment.
  * `contains()`: Checking the string for any content, e.g., `contains(env.SOURCECRAFT_COMMIT_REF_NAME, "release")` or `env.SOURCECRAFT_COMMIT_REF_NAME.contains("release")`.
  * `cubes.<cube_name>.status`: [Checking](#check-any-prev-status) the status of any previous cube.
  * `failure()` and `success()`: Checking the summary status of all cubes that have completed their work before the current one.
  * `==`: Comparison, e.g., `env.SOURCECRAFT_COMMIT_REF_NAME == "main"`.
  * `!=`: Negation, e.g., `env.SOURCECRAFT_COMMIT_REF_NAME != "main"`.
  * `&&`: The "AND" operator, e.g., `contains(env.SOURCECRAFT_COMMIT_REF_NAME, "release") && env.SOURCECRAFT_BASE_REF == "main"`.
  * `||`: The "OR" operator, e.g., `contains(env.SOURCECRAFT_COMMIT_REF_NAME, "qwerty") || env.SOURCECRAFT_COMMIT_REF_NAME == "non-existing-ref"`. 

  For more information, see [Example of a configuration with conditional cube execution](#cubes-with-condition).
* `image`: Docker image used to execute the cube. The `image` and `devcontainer` sections are mutually exclusive. For more information, see [image](#image).
* `name`: Cube name. This is a required setting.
* `needs`: List of cubes to execute before the current one.
* `retry`: [Automatic cube restart](#auto-retry).
* `script`: Command to execute in the cube.
* `uses`: Enables reusing another cube’s parameters in the current cube. The syntax depends on the location of the cube to reuse:
  * `uses: <cube_name>`: For cubes defined in `.sourcecraft/ci.yaml`. For more information, see [Example of reusing cube parameters](#cubes-uses).
  * `uses: ./<repository_file_path>/cubes/<cube_name>`: For cubes defined in a YAML file in the same the repository. For more information, see [Example of reusing cube parameters from a YAML file in the same repository](#cubes-uses-file). The number of files with cubes and the number of cubes per file are unlimited.

    {% note warning %}

    The path must begin with `./`. Make sure to specify `/cubes/<cube_name>` after the file path.

    {% endnote %}

  * `uses: <organization_slug>/<repository_slug>/<repository_file_path>/cubes/<cube_name>`: For cubes defined in a YAML file in another repository. For more information, see [Example of reusing cube parameters from a YAML file in another repository](#cubes-uses-repo-file).

    {% note warning %}

    To reuse a cube from another repository, the cube must have the `exported: true` flag. If this flag is not set, an attempt to reuse the cube in another repository will fail with an error.

    {% endnote %}

  You can redefine some of the current cube’s parameters. For more information, see [Example of reusing cube parameters](#cubes-uses).
* `with`: GitHub Action parameters. It can only be used together with `action`.

<!-- source: en/_includes/sourcecraft/ci-cd/gh-gl-cloud-workers.md -->
{% note warning %}

Only [cloud workers](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/workers.md#cloud-workers) support running GitHub Actions or GitLab pipelines in SourceCraft CI/CD.

{% endnote %}
<!-- endsource: en/_includes/sourcecraft/ci-cd/gh-gl-cloud-workers.md -->

##### Example of a cube configuration using variables, including predefined ones {#cubes-with-vars}

<!-- source: en/_includes/sourcecraft/ci-cd/config-with-vars.md -->
```yaml
# Defining global variables
# to provide to all cubes of all tasks in all workflows.
env:
  GLOBAL_VAR: global_var
  GLOBAL_SECRET: ${{ secrets.<secret_name> }}

workflows:
  my-workflow:
    # Here you define variables that will be available in all cubes 
    # of all my-workflow tasks
    env:
      WORKFLOW_VAR: workflow-var
    
    tasks:
      - name: my-task
        # Here you define variables that will be available in all cubes 
        # within my-task
        env:
          TASK_ENV_VAR: This variable is available in all cubes of this task.
          # Multi-line variable
          MULTILINE_VAR: |
            multi-var
            multi-var
            this is my multi-var
        
        cubes:
          - name: my-cube-1
            # Here you define variables that will only be available
            # within my-cube-1
            env:
              CUBE_ENV_VAR: This variable is available only in cube my-cube-1.
              # Variable with a value from a secret
              SECRET_VAR: ${{ secrets.<secret_name> }}
              # Reusing global variables, 
              # e.g., GLOBAL_VAR and GLOBAL_SECRET
              LOCAL_VAR: ${{ env.<global_variable_1> }}
              LOCAL_SECRET: ${{ env.<global_variable_2> }}
              # Reusing workflow variables,
              # e.g., WORKFLOW_VAR
              LOCAL_VAR2: ${{ env.<workflow_variable> }}

            script:
              - echo "$TASK_ENV_VAR"
              - echo "$MULTILINE_VAR"
              - echo "$CUBE_ENV_VAR"
              - echo "$SECRET_VAR"
              - echo "$WORKFLOW_VAR"
              - echo "$LOCAL_VAR"
              - echo "$LOCAL_VAR2"
              - echo "$LOCAL_SECRET"

          - name: my-cube-2
            # Here you define variables that will only be available 
            # within my-cube-2
            env:
              CUBE_ENV_VAR: This variable is available only in cube my-cube-2.
            script:
              - echo "$TASK_ENV_VAR"
              - echo "$CUBE_ENV_VAR"
              # Using a predefined variable
              - echo "$SOURCECRAFT_TASK"
              - echo "$WORKFLOW_VAR"
              - echo "$GLOBAL_VAR"

      - name: my-task-2
        cubes:
          - name: my-cube-3
            script:
              - echo "$WORKFLOW_VAR"
              - echo "$GLOBAL_VAR"
```
<!-- endsource: en/_includes/sourcecraft/ci-cd/config-with-vars.md -->

For more information, see [Predefined environment variables](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/predefined-variables.md) and [Processing environment variables in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/variables.md).

##### Example of a cube configuration using artifacts {#cubes-with-artifacts}

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: delete-git
            script:
              - env
              - rm -rfv ./git
            artifacts:
              paths:
                - ./test.cpp
```

See also an example of using artifacts for Java in [Examples](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/ci-cd.md#examples).


##### Example of a configuration with cube dependencies {#cubes-with-needs}

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: vendor
            script:
              - make vendor

          - name: build-client
            needs: [ "vendor" ]
            script:
              - go build -C cmd/client
            artifacts:
              paths:
                - cmd/client/client

          - name: build-server
            needs: [ "vendor" ]
            script:
              - go build -C cmd/server/server
            artifacts:
              paths:
                - cmd/server/server

          - name: run-tests
            needs: [ "build-client", "build-server" ]
            script:
              - go test ./...
```

##### Example of reusing cube parameters {#cubes-uses}

```yaml
cubes:
  - name: external-cube
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR

tasks:
  - name: first-task
    cubes:
      - name: first-cube
        uses: external-cube
      # Reusing a cube with a redefined parameter
      - name: second-cube
        env:
          CUBE_VAR: world
        uses: external-cube

workflows:
  first-workflow:
    tasks:
      - first-task
```

##### Example of reusing cube parameters from a YAML file in the same repository {#cubes-uses-file}

The `.ci-files/cubes/bash-lib.yaml` file containing the cube to reuse:

```yaml
cubes:
  - name: external-cube-1
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR
  - name: external-cube-2
    script:
      - echo "world"
```

`.sourcecraft/ci.yaml`:

```yaml
tasks:
  - name: first-task
    cubes:
      - name: first-cube
        uses: ./.ci-files/cubes/bash-lib.yaml/cubes/external-cube-1

workflows:
  first-workflow:
    tasks:
      - first-task
      - second-task:
        cubes:
          - name: second-cube
            uses: ./.ci-files/cubes/bash-lib.yaml/cubes/external-cube-2
```

##### Example of reusing cube parameters from a YAML file in another repository {#cubes-uses-repo-file}

The `.ci-files/cubes/bash-lib.yaml` file with the cube to reuse, stored in the `myrepo` repository of the `myorg` organization:

```yaml
cubes:
  - name: external-cube-1
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR
    # Flag that enables using the cube in other repositories
    exported: true
  - name: external-cube-2
    script:
      - echo "world"
    exported: true
```

The repository’s `.sourcecraft/ci.yaml` file containing the CI configuration:

```yaml
tasks:
  - name: first-task
    cubes:
      - name: first-cube
        uses: myorg/myrepo/.ci-files/cubes/bash-lib.yaml/cubes/external-cube-1

workflows:
  first-workflow:
    tasks:
      - first-task
      - second-task:
        cubes:
          - name: second-cube
            uses: myorg/myrepo/.ci-files/cubes/bash-lib.yaml/cubes/external-cube-2
```

##### Example of a configuration where the task continues despite cube failures {#cubes-with-allow-failure}

```yaml
workflows:
  workflow-name:
    tasks:
      - name: task-name
        cubes:
          - name: failing-cube
            allow_failure: true
```

##### Example of a configuration with conditional cube execution {#cubes-with-condition}

```yaml
workflows:
  workflow-name:
    tasks:
      - name: task-name
        cubes:
          # The cube will be executed only if the workflow has been executed in the branch whose name 
          # contains "release", and the target branch in the pull request is "main"
          - name: condition-cube-1
            if: contains(env.SOURCECRAFT_COMMIT_REF_NAME, "release") && env.SOURCECRAFT_BASE_REF == "main"
            script:
              - echo 'The source branch name contains text "release" and the target branch is "main".'

          # The cube will be executed only if the workflow has been executed in the branch whose name
          # contains "feature", and the target branch in the pull request is not "main"
          - name: condition-cube-2
            if: env.SOURCECRAFT_COMMIT_REF_NAME.contains("feature") || env.SOURCECRAFT_BASE_REF != "main"
            script:
              - echo 'The source branch name contains text "feature" or the target branch is not "main".'

          # Executing a cube regardless of whether the previous cubes were successful 
          # or not
          - name: condition-cube-3
            if: always()
            script:
              - env -i bash
```

## Docker images {#image}

The `image` section contains parameters of the Docker image used to execute the cube. You can specify a standard Docker image name or a path in a particular registry.

{% note tip %}

Instead of `image`, you can use the [devcontainer](#devcontainer) section to run a cube in the environment defined in the Development Container specification. The `image` and `devcontainer` sections are mutually exclusive.

If neither the `image` nor the `devcontainer` section is specified, the commands will run in the Linux environment.

{% endnote %}

Supported optional properties:
* `args`: Arguments to provide as input to a starting container. You cannot use this property in a cube where the `script` property is specified.
* `entrypoint`: Redefining the container entry point. Same as the `--entrypoint` flag for the `docker run` command.

  To learn more about using the entry point and arguments, see the [relevant section](#entrypoint-and-args).
* `name`: Path to the Docker image in the registry.
* `password`: Password to access the registry. You may want to use [secrets](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#secrets) to store your passwords.
* `username`: Username to access the registry.

##### Example of a Docker image configuration with a standard name {#image-standard-name}

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: my-cube
            image: ubuntu:22.04
            script: echo "hello world!"
```

##### Example of a Docker image configuration specifying a path in a particular registry {#image-path}

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: my-cube
            image: cr.yandex/mirror/ubuntu:22.04
            script: echo "hello world!"
```

##### Example of a Docker image configuration with authentication {#image-auth}

If authentication is required to access the registry, you can use the `docker login` command in your task or configure authentication in the `image` section and use a [secret](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/index.md#secrets), e.g.:

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: my-cube
            image:
              name: some-docker-registry.com/account-name/ubuntu:22.04
              username: username 
              password: ${{ secrets.<secret_name> }}
```

For more information about working with secrets, see [Managing secrets in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/secrets.md).

## Entry point and arguments {#entrypoint-and-args}

### Running commands in a Docker container {#run-commands-in-container}

To run commands in the container context, specify the Docker image path in the registry using the `image` or `image:name` property, and provide the commands in the `script` property, e.g.:

```yaml
cubes:
  - name: greet
    env:
      GREETING: "Hello"
    image: docker.io/library/node
    script:
      - echo $GREETING
```

If the container has a redefined entry point, you will need to reset the latter before running a command from `script`. You can do this by specifying `""` in the `entrypoint` property. For example, you can use a container that has the `ENTRYPOINT ["/usr/bin/docker"]` entry point set by default:

```yaml
cubes:
  - name: greet
    env:
      GREETING: "Hello"
    image:
      name: some-docker-registry.com/cloud-builders/docker
      entrypoint: ""
    script:
      - echo $GREETING
```

### Providing command-line arguments to a Docker container {#pass-args-to-container}

To provide arguments, which you need to run a container, to a container with a redefined entry point, use the `args` property. For example, this may be the case for a container used to create a new Docker image:

```yaml
cubes:
  - name: build-and-greet
    image:
      name: some-docker-registry.com/cloud-builders/docker
      args: ["build", "-t", "hello-world", "."]
```

Alternative configuration:

```yaml
cubes:
  - name: build-and-greet
    image:
      name: some-docker-registry.com/cloud-builders/docker
      args:
        - 'build'
        - '-t'
        - 'hello-world'
        - '.'
```

{% note tip %}

To flexibly solve your CI/CD tasks using Docker containers, you can use `entrypoint` and `args` properties together.

{% endnote %}

Example of using `entrypoint` and `args` together:

```yaml
cubes:
  - name: test
    image:
      name: docker.io/library/python:3.13-slim
      entrypoint: "/bin/bash"
      args: ["-c", "'pip install flask && python test_app.py -v'"]
```

Alternative configuration using `script`:

```yaml
cubes:
  - name: test
    image: docker.io/library/python:3.13-slim
    script:
      - pip install flask
      - python test_app.py -v
```

The `script: [commands]` property is an alternative to `entrypoint: "default shell"` and `args: ["-c", 'command_1 && … && command_N']`.

{% note warning %}

You cannot specify both `image:args` and `script` at the same time in the same cube.

{% endnote %}

## Development Container (devcontainer) environment {#devcontainer}

The `devcontainer` section allows you to run a cube in the environment defined in the [Development Container specification](https://containers.dev/implementors/spec/). When the cube runs, the system uses the configuration in the repository to build a container to then run the command from the `script` section in that container.

{% note tip %}

Instead of `devcontainer`, you can use the [image](#image) section to run a cube in the environment of a specific Docker image. The `image` and `devcontainer` sections are mutually exclusive.

If neither the `image` nor the `devcontainer` section is specified, the commands will run in the Linux environment. 

{% endnote %}

[Sample Development Container specifications](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/spaces-env-config.md#examples)

The `devcontainer` section must include the `workspace_folder` parameter which specifies the path to the repository directory containing the `devcontainer.json` and `Dockerfile` files, as well as other specification-related files.

##### Example of a cube configuration with devcontainer {#devcontainer-example}

`devcontainer_tests/simple/devcontainer.json`:

```json
{
  "name": "Rust Dev Container",
  "build": {
    "dockerfile": "Dockerfile"
  },
  "customizations": {
    "vscode": {
      "extensions": [
        "rust-lang.rust-analyzer"
      ]
    }
  },
  "postCreateCommand": "cargo fetch"
}
```

`devcontainer_tests/simple/Dockerfile`:

```Dockerfile
FROM rust:1.95-alpine

RUN cargo version

WORKDIR /workspace
```

`.sourcecraft/ci.yaml`:

```yaml
workflows:
  my-workflow:
    tasks:
      - name: my-task
        cubes:
          - name: simple-devcontainer
            devcontainer:
              workspace_folder: "./devcontainer_tests/simple"
            script:
              - cargo version
```

The example below uses the `simple-devcontainer` cube to build an environment based on the configuration from the `devcontainer_tests/simple` directory and run the `cargo version` command.

## Automatic cube restart {#auto-retry}

To allow automatic cube restart, set the `retry` parameter. Use it to specify the maximum number of retries and the restart conditions.

Each restart:

* Clears the environment variables (`env`) added during the previous attempt.
* Clears the data written to the `outputs` section during the previous attempt.
* Artifacts created during the execution of the cube are saved only for the last attempt, whether or not it was successful.
* No data is cleared on the file system. It is for you to check that data that may have been changed will not affect the outcome of the restart.
* When you `cancel` a task, the restart mechanism gets blocked and the cube does not restart.

If you set both `retry` and `allow_failure`, the cube will restart as many times as specified in `retry`.

### Restart by default {#retry-default}

```yaml
cubes:
  - name: cube1
    ...
    retry: 3
```

In this example:

* `retry`: Maximum number of retries. After the initial start, the cube will be restarted a maximum of three times.
* The restart conditions are not specified, so a restart is equally possible on execution error or timeout.

### Restart with conditions {#retry-conditions}

```yaml
cubes:
  - name: cube2
    ...
    retry:
      max: 3
      on_error_types:
        - timeout
```

In this example:

* `max`: Maximum number of retries. After the initial start, the cube will be restarted a maximum of three times.
* `on_error_types`: Restart conditions:
    * `timeout`: Restart on timeout.

## Checking the status of previous cubes {#check-prev-statuses}

The following statuses are possible:

* `success`: Success.
* `failure`: Failure due to an error.
* `ignored_failure`: Formal success. Ignored error transformed from `failure` with `allow_failure=true` enabled.
* `timeout`: Failure. Execution interrupted by timeout.
* `ignored_timeout`: Formal success. Ignored timeout transformed from `timeout` with `allow_failure=true` enabled.
* `skipped`: Cube skipped. Not executed because the `if` condition returned `false`.
* `cancelled`: Cube canceled. Entire workflow canceled by the user.

### Checking the status of any previous cube {#check-any-prev-status}

To check the status of any previous cube, use the `cubes.<cube_name>.status == <status>` expression format in the `if` condition.

**Example**

```yaml
cubes:
  # Cube 1: Successful cube
  - name: success-cube
    script:
      - echo "This cube must succeed"

  # Cube 2: Checking the success status of the previous cube
  - name: if-success-cube
    if: cubes.success-cube.status == "success"
    needs:
      - success-cube
    script:
      - echo "success-cube succeeded (expected)!"
```

### Checking the summary status of all previous cubes {#check-all-prev-statuses}

To check the summary status of all cubes that have completed their work before the current one, use the following functions in the `if` condition:

* `success()`: returns `true` if all previous cubes were successful or nearly successful.

    Statuses that meet the condition:

    * `success`
    * `skipped`
    * `ignored_failure`
    * `ignored_timeout`

* `failure()`: returns `true` if at least one of the previous cubes failed.

    Statuses that meet the condition:

    * `failure`
    * `timeout`
    * `cancelled`

**Example**

```yaml
cubes:
# Cube 1: Successful cube
- name: success-cube
  script:
    - echo "This cube must succeed"

# Cube 2a: Checking the success status of the previous cube
- name: if-success-cube
  # if-condition for checking the status of any previous cube
  if: cubes.success-cube.status == "success"
  needs:
    - success-cube
  script:
    - echo "success-cube succeeded (expected)!"

# Cube 2b: Checking the failure status of the previous cube
- name: if-failure-cube
  # if-condition for checking the summary status of all cubes that have completed their work before this cube
  if: failure() || !success()
  needs:
    - success-cube
  script:
    - echo "success-cube failed (not expected)!"
    - exit 1

# Cube 3: Cube with an error
- name: failed-cube
  allow_failure: true
  needs:
    - if-success-cube
    - if-failure-cube
  script:
    - echo "This cube must fail"
    - exit 1

# Cube 4a: Checking the failure status of the previous cube
- name: if-success-cube-2
  if: cubes.failed-cube.status == "success"
  needs:
    - failed-cube
  script:
    - echo "failed-cube succeeded (not expected)!"
    - exit 1

# Cube 4b: Checking the failure status of the previous cube
- name: if-failure-cube-2
  if: cubes.failed-cube.status == "ignored_failure"
  needs:
    - failed-cube
  script:
    - echo "failed-cube failed (expected)!"
```

You can also check the execution status of previous cubes in scripts by using the following syntax for `outputs`: `${{ cubes.<cube-name>.status }}`.

**Example**

```text
if [ "${{ cubes.retrycube.status }}" == "success" ]; then
  echo "Retry cube succeeded!"
else
  echo "Retry cube failed!"
fi
```

#### Useful links {#see-also}

* [Tasks](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/tasks.md)
* [Trigger events (on)](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/on.md)
* [Workflows](https://sourcecraft.dev/portal/docs/en/sourcecraft/ci-cd-ref/workflows.md)
* [Continuous integration and continuous deployment in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/ci-cd.md)
* [Configuring CI/CD in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/ci-cd.md)
* [Managing secrets in a SourceCraft repository](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/secrets.md)
* [Processing environment variables in SourceCraft](https://sourcecraft.dev/portal/docs/en/sourcecraft/operations/variables.md)
* [Development Containers in SourceCraft Spaces](https://sourcecraft.dev/portal/docs/en/sourcecraft/concepts/spaces-env-config.md)