Cubes

The cubes section lists the minimum logical actions, i.e., cubes, to execute within a task.

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.

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, respectively.

To configure a Docker cube, use the 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. This cube builds a container based on the configuration stored in the repository and runs a custom script in that container.

A devcontainer cube is specified in the devcontainer property which contains the path to the directory with the devcontainer.json or Dockerfile specification.

Sample Development Container specifications
Cube with AI skill: Runs an AI skill available in the repository. You set such a cube using the skill parameter, which gives the service name of the skill. For more information, see Running a skill in CI/CD.

In cubes, you can use environment variables and secrets. To provide environment variables from a certain cube to others as KEY=VALUE pairs, you can use the $SOURCECRAFT_ENV predefined variable.

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 CI/CD section of the repository for 14 days.

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.
allow_failure: Flag to control your CI/CD workflow 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.
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 CI/CD section of the repository for 14 days. For more information, see Example of a cube configuration using artifacts.
env: Environment variables that are only available in a specific cube. For more information, see Example of a cube configuration using variables, including predefined ones.
Tip
You can also set environment variables within the following sections:
- workflows: Variables will be available to all cubes of all tasks within a specific workflow.
- tasks: Variables will be available in all cubes of a certain task.
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.
gitlab_workflow: Path to the GitLab pipeline configuration file. For more information, see GitLab pipelines in the SourceCraft CI/CD.
if: Cube execution condition. If the condition is not met, the cube is skipped and the job continues.

If the condition does not contain calls to success(), failure(), or always(), the system automatically adds a success() check: success() && (<other_condition>). Therefore, if the previous cube in the same job fails, the current cube is skipped even if the specified condition is met. Failures of cubes with allow_failure: true do not prevent subsequent cubes from running.

If the condition already contains a call to at least one of these functions, no additional success() check is added.

Supported functions, expressions, and 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 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 in the same job.
- ==: 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.
image: Docker image used to execute the cube. The image and devcontainer sections are mutually exclusive. For more information, see image.
name: Cube name. This is a required setting.
needs: List of cubes to execute before the current one.
retry: Automatic cube restart.
script: Command to execute in the cube.
skill: Service name of the AI skill to run in the cube. Provide it without /. For more information, see Running a skill in CI/CD.
uses: Parameter that allows the current cube to reuse parameters from another cube defined in the same .sourcecraft/ci.yaml file, any YAML file in the same repository, or any YAML file in another repository. For more information, see Reusing cube parameters.
with: GitHub Action or AI skill parameters; used together with action or skill.

Warning

Only cloud workers support running GitHub Actions or GitLab pipelines in SourceCraft CI/CD.

Example of a cube configuration using variables, including predefined ones

# 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"

For more information, see Predefined environment variables and Processing environment variables in SourceCraft.

Example of a cube configuration using artifacts

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

See an example of using artifacts for Java in Examples.

Example of a configuration with cube dependencies

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 a configuration where the task continues despite cube failures

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

Example of a configuration with conditional cube execution

workflows:
  workflow-name:
    tasks:
      - name: task-name
        cubes:
          # The cube will be executed if success() returns _true_, the source branch name
          # contains "release", and the target branch in the pool 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 if success() returns _true_ and at least one of the following conditions is met:
          # the source branch name contains "feature", and the target branch 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

To check the condition regardless of errors in previous cubes, add a call to always(). For example, the following condition checks only the branch name:

if: always() && env.SOURCECRAFT_COMMIT_REF_NAME == "main"

Example of a cube configuration that runs an AI skill

This example uses the issue-summary skill that creates an issue summary. Import the skill from the catalog before running it. In the issue_link parameter, specify the link to the issue.

workflows:
  skill-workflow:
    tasks:
      - name: skill-task
        cubes:
          - name: skill-cube
            skill: issue-summary
            with:
              issue_link: https://sourcecraft.dev/<organization_slug>/<repository_slug>/issues/<task_number>

Tip

You can use multiple AI skill cubes in a single task and add regular cubes to them.

Docker images

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.

Tip

Instead of image, you can use the 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.

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.
name: Path to the Docker image in the registry.
password: Password to access the registry. You may want to use secrets to store your passwords.
username: Username to access the registry.

Example of a Docker image configuration with a standard name

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

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

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, e.g.:

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.

Entry point and arguments

Running commands in a Docker 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.:

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:

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

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:

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

Alternative configuration:

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

Tip

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

Example of using entrypoint and args together:

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:

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'].

Warning

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

Development Container (devcontainer) environment

The devcontainer section allows you to run a cube in the environment defined in the Development Container specification. When you start a cube, the system uses configuration from the repository to build a container and use it to run the command from the script section.

Tip

Instead of devcontainer, you can use the 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.

Sample Development Container specifications

The devcontainer section must include the workspace_folder parameter which specifies the path to the repository's working directory. You can land the environment configuration file either at .devcontainer.json or .devcontainer/devcontainer.json relative to this directory. The directory may also contain files used in the environment configuration, such as Dockerfile.

Example of a cube configuration with devcontainer

devcontainer_tests/simple/.devcontainer.json:

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

devcontainer_tests/simple/Dockerfile:

FROM rust:1.95-alpine

RUN cargo version

WORKDIR /workspace

.sourcecraft/ci.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.

Reusing cube parameters

You can use the uses parameter in the current cube to reuse the parameters of another 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 within a single .sourcecraft/ci.yaml file.
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. The number of files with cubes and the number of cubes per file are unlimited.

Warning

The path must begin with ./. Make sure there is /cubes/<cube_name> after the file path.
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.

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.

You can redefine some of the current cube’s parameters. For more information, see Example of reusing cube parameters within a single .sourcecraft/ci.yaml file.

Example of reusing cube parameters within a single .sourcecraft/ci.yaml file

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

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

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

.sourcecraft/ci.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
      - name: 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

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

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:

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
      - name: second-task
        cubes:
          - name: second-cube
            uses: myorg/myrepo/.ci-files/cubes/bash-lib.yaml/cubes/external-cube-2

Automatic cube restart

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

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

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

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

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

Checking the status with cubes.<cube_name>.status does not disable automatic addition of success(). To execute a cube after a specific cube fails, add a call to failure() or always(), such as follows:

if: failure() && cubes.failed-cube.status == "failure"

Example

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

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

success(): Returns true if all previous cubes completed successfully, were skipped, or failed with errors allowed by allow_failure: true.

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
Failures of cubes with allow_failure: true do not trigger failure().
always(): Returns true regardless of the status of previous cubes. Use this function to execute a cube even after an error, e.g., to clean up the environment.

If the if condition contains no calls to success(), failure(), or always(), a success() check is added automatically. Calling any of these functions allows you to explicitly define how the results of previous cubes affect whether the current one runs.

Example

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

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

Useful links

Was the article helpful?

Tasks

Reusing workflows and cubes