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.

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:

  • name: Cube name.
  • script: Command to execute in the cube.
  • needs: List of cubes to execute before the current one.
  • image: Docker image used to execute the cube. This is an optional property. For more information, see image.
  • env: Environment variables that are only available in a specific cube.
  • 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.

Example of a cube configuration using variables, including predefined ones

workflows:
  my-workflow:
    tasks:
      - name: my-task
        # Here you define variables that will be shared among all cubes
        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 this cube
            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> }}
            script:
              - echo "$TASK_ENV_VAR"
              - echo "$MULTILINE_VAR"
              - echo "$CUBE_ENV_VAR"
              - echo "$SECRET_VAR"                
          - name: my-cube-2
            # Here you define variables that will only be available within this cube
            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"

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 also 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 ./...

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.

If the image section is not specified, the commands will be executed in Linux environment.

Supported optional properties:

  • name: Path to the Docker image in the registry.

  • username: Username to access the registry.

  • password: Password to access the registry. You may want to use secrets to store your passwords.

  • entrypoint: Redefining the container entry point. Same as the --entrypoint flag for the docker run command.

  • args: Arguments to provide as input to a starting container. You cannot use this property in a cube where the script property is specified.

    To learn more about using the entry point and arguments, see the relevant section.

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.

See also

Previous
Tasks
Next
Predefined environment variables