---
metadata:
  - name: generator
    content: Diplodoc Platform v5.57.3
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: https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/cubes.md
    type: text/markdown
    title: Markdown version
  - href: https://sourcecraft.dev/portal/docs/ru/llms.txt
    type: text/markdown
    title: llms.txt
title: Кубики (cubes)
description: 'Параметры кубиков в CI/CD SourceCraft: команды, окружение, зависимости и переиспользование.'
---
> **Documentation Index:** Fetch the complete configuration index at https://sourcecraft.dev/portal/docs/ru/llms.txt


# Кубики (cubes)

<!-- source: ru/_includes/sourcecraft/ci-cd/cubes-description.md -->
В блоке `cubes` определяется перечень минимальных логических действий — _кубиков_, которые будут выполняться в [задании](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/ci-cd.md#tasks).

Минимальным действием может быть вызов скрипта или запуск Docker-контейнера. Также может быть вариант вызова скрипта в Docker-контейнере.

Есть следующие виды кубиков:

* _Нативный_ — выполняется напрямую на [воркере](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/workers.md). 

  Если нативный кубик в процессе выполнения изменит окружение воркера, например, установит пакет, создаст или удалит файл и т. д., это окружение останется для всех последующих кубиков, которые выполняются в рамках одного задания.

* _Docker-кубик_ — выполняется внутри Docker-контейнера, который запускается на воркере. Внутри контейнера запускается пользовательский скрипт или скрипт контейнера, если для контейнера предусмотрена точка входа (entrypoint).

  Если Docker-кубик в процессе выполнения изменит окружение, оно будет доступно последующим кубикам задания, только если изменения производятся внутри директории `/sourcecraft`. Все остальные изменения удаляются вместе с Docker-контейнером.

  При работе из контейнера директории монтируются следующим образом:
  * директория, в которой находятся связанные с выполняемым заданием файлы, монтируется по пути `/sourcecraft`;
  * директория, в которую клонируется репозиторий, и которая по умолчанию назначается рабочей (`workdir`), монтируется по пути `/sourcecraft/workspace`.

  Пути указанных директорий можно получить из [предопределенных переменных окружения](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/predefined-variables.md) `$SOURCECRAFT_ROOT_DIRECTORY` и `$SOURCECRAFT_WORKSPACE` соответственно.

  Docker-кубик задается с помощью параметра [image](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/cubes.md#image), в котором указывается название Docker-образа, а также опционально логин, пароль, точка входа и аргументы.

* _Devcontainer-кубик_ — выполняется в окружении, которое задано [спецификацией Development Container](https://containers.dev/implementors/spec/). Такой кубик собирает контейнер по конфигурации из репозитория и запускает в нем пользовательский скрипт.

  Devcontainer-кубик задается с помощью параметра [devcontainer](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/cubes.md#devcontainer), в котором указывается путь к директории со спецификацией `devcontainer.json` и `Dockerfile`. 
  
  [Примеры спецификаций Development Container](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/spaces-env-config.md#examples)

* _Кубик с AI-навыком_ — запускает [AI-навык](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/ai-skills.md), доступный в репозитории. Такой кубик задается с помощью параметра `skill`, в котором указывается служебное имя навыка. Подробнее в подразделе [Запустить навык в CI/CD](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/ai-skills.md#run-skill-ci-cd).

В кубиках вы можете использовать [переменные окружения](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/ci-cd.md#variables), а также [секреты](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/index.md#secrets). Для передачи переменных окружения от одного кубика к последующим в виде пар `KEY=VALUE` предусмотрена [предопределенная переменная](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/predefined-variables.md) `$SOURCECRAFT_ENV`.

Кубики внутри одного задания по умолчанию запускаются последовательно. Кубики могут быть связаны между собой через параметр `needs`. В параметре указывается список кубиков, которые должны быть выполнены до запуска текущего. Если параметр не указан, кубик будет зависеть от кубика, который определен непосредственно перед ним.

Артефакты, которые могут быть созданы в результате работы кубика, сохраняются для дальнейшего использования. Их можно скачать из конкретного кубика в секции ![image](../../_assets/console-icons/arrows-3-rotate-right.svg) **CI/CD** репозитория в течение 14 дней.
<!-- endsource: ru/_includes/sourcecraft/ci-cd/cubes-description.md -->

Поддерживаются следующие параметры:
* `action` — название и версия GitHub Action, например `docker/setup-buildx-action@v3.11.1`. Подробнее на странице [Интеграция с GitHub Actions в SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/gh-actions.md).
* `allow_failure` — флаг, позволяющий управлять поведением CI/CD-процесса при возникновении ошибок в отдельных кубиках. При значении `true` выполнение задания продолжится даже в случае ошибки в кубике, как если бы он завершился успешно. Значение по умолчанию — `false`. Подробнее в подразделе [Пример конфигурации, при которой задание продолжится даже после завершения кубика ошибкой](#cubes-with-allow-failure).
* `artifacts` — список путей к файлам, которые будут созданы в результате работы кубика и сохранены для дальнейшего использования. Артефакты можно будет скачать из конкретного кубика в секции ![image](../../_assets/console-icons/arrows-3-rotate-right.svg) **CI/CD** репозитория в течение 14 дней. Подробнее в подразделе [Пример конфигурации кубиков с использованием артефактов](#cubes-with-artifacts).
* `env` — [переменные окружения](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/ci-cd.md#variables), доступные только в конкретном кубике. Подробнее в подразделе [Пример конфигурации кубиков с использованием переменных, в том числе предопределенных](#cubes-with-vars).

  {% note tip %}

  Также вы можете задать переменные окружения внутри следующих блоков:
  * [workflows](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/workflows.md) — переменные будут доступны во всех кубиках всех заданий конкретного рабочего процесса.
  * [tasks](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/tasks.md) — переменные будут доступны во всех кубиках конкретного задания.

  {% endnote %}

* `exported` — флаг, разрешающий при значении `true` переиспользовать кубик в другом репозитории. Значение по умолчанию — `false`. Подробнее в подразделе [Пример переиспользования параметров кубика из произвольного YAML-файла другого репозитория](#cubes-uses-repo-file).
* `gitlab_workflow` — путь к файлу с конфигурацией пайплайна GitLab. Подробнее на странице [Пайплайны GitLab в CI/CD SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/gl-pipelines.md).
* `if` — условие, при котором кубик будет выполнен. Если условие не выполнено, кубик пропускается, а задание продолжает выполняться. Поддерживаются следующие операторы:
  * `always()` — выполнить кубик вне зависимости от того, успешно ли выполнились предыдущие кубики или нет. Например, если нужно очистить окружение.
  * `contains()` — проверка наличия в строке какого-либо содержимого, например `contains(env.SOURCECRAFT_COMMIT_REF_NAME, "release")` или `env.SOURCECRAFT_COMMIT_REF_NAME.contains("release")`.
  * `cubes.<имя_кубика>.status` — [проверка](#check-any-prev-status) статуса любого предыдущего кубика.
  * `failure()` и `success()` — [проверка](#check-all-prev-statuses) сводного статуса по всем кубикам, завершившим работу до текущего.
  * `==` — сравнение, например `env.SOURCECRAFT_COMMIT_REF_NAME == "main"`.
  * `!=` — отрицание, например `env.SOURCECRAFT_COMMIT_REF_NAME != "main"`.
  * `&&` — оператор «И», например `contains(env.SOURCECRAFT_COMMIT_REF_NAME, "release") && env.SOURCECRAFT_BASE_REF == "main"`.
  * `||` — оператор «ИЛИ», например `contains(env.SOURCECRAFT_COMMIT_REF_NAME, "qwerty") || env.SOURCECRAFT_COMMIT_REF_NAME == "non-existing-ref"`. 

  Подробнее в подразделе [Пример конфигурации с условным исполнением кубиков](#cubes-with-condition).
* `image` — Docker-образ, который будет использоваться для выполнения кубика. Блоки `image` или `devcontainer` взаимоисключающие. Подробнее в подразделе [image](#image).
* `name` — имя кубика. Обязательный параметр.
* `needs` — список кубиков, которые должны быть выполнены до выполнения текущего.
* `retry` — [автоматический перезапуск](#auto-retry) кубика.
* `script` — команда, которая будет выполнена в кубике.
* `skill` — служебное имя [AI-навыка](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/ai-skills.md), который будет запущен в кубике. Указывается без `/`. Подробнее в подразделе [Запустить навык в CI/CD](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/ai-skills.md#run-skill-ci-cd).
* `uses` — параметр, с помощью которого в текущем кубике можно переиспользовать параметры другого кубика, определенного в этом же `.sourcecraft/ci.yaml`, в произвольном YAML-файле этого же репозитория или произвольном YAML-файле другого репозитория. Подробнее в подразделе [Переиспользование параметров кубиков](#reusable-cubes).
* `with` — параметры GitHub Action или AI-навыка. Используется совместно с `action` или `skill`.

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

Запуск GitHub Actions и пайплайнов GitLab в CI/CD SourceCraft поддерживается только на [облачных воркерах](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/workers.md#cloud-workers).

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

##### Пример конфигурации кубиков с использованием переменных, в том числе предопределенных {#cubes-with-vars}

<!-- source: ru/_includes/sourcecraft/ci-cd/config-with-vars.md -->
```yaml
# Здесь определяются переменные с глобальной областью видимости,
# они будут переданы во все кубики всех заданий во всех рабочих процессах
env:
  GLOBAL_VAR: global_var
  GLOBAL_SECRET: ${{ secrets.<название_секрета> }}

workflows:
  my-workflow:
    # Здесь определяются переменные, которые будут доступны во всех кубиках 
    # всех заданий рабочего процесса my-workflow
    env:
      WORKFLOW_VAR: workflow-var
    
    tasks:
      - name: my-task
        # Здесь определяются переменные, которые будут доступны во всех кубиках 
        # внутри задания my-task
        env:
          TASK_ENV_VAR: This variable is available in all cubes of this task.
          # Многострочная переменная
          MULTILINE_VAR: |
            multi-var
            multi-var
            this is my multi-var
        
        cubes:
          - name: my-cube-1
            # Здесь определяются переменные, которые будут доступны только внутри
            # кубика my-cube-1
            env:
              CUBE_ENV_VAR: This variable is available only in cube my-cube-1.
              # Переменная, значение которой задается из секрета
              SECRET_VAR: ${{ secrets.<название_секрета> }}
              # Переиспользование переменных из глобальной области видимости, 
              # например GLOBAL_VAR и GLOBAL_SECRET
              LOCAL_VAR: ${{ env.<глобальная_переменная_1> }}
              LOCAL_SECRET: ${{ env.<глобальная_переменная_2> }}
              # Переиспользование переменных из области видимости рабочего
              # процесса, например WORKFLOW_VAR
              LOCAL_VAR2: ${{ env.<переменная_рабочего_процесса> }}

            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
            # Здесь определяются переменные, которые будут доступны только внутри 
            # кубика 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"
              # Использование предопределенной переменной
              - 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: ru/_includes/sourcecraft/ci-cd/config-with-vars.md -->

Подробнее о предопределенных переменных на странице [Предопределенные переменные окружения](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/predefined-variables.md), о работе с переменными окружения — на странице [Работа с переменными окружения в SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/variables.md).

##### Пример конфигурации кубиков с использованием артефактов {#cubes-with-artifacts}

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

Пример использования артефактов для Java в подразделе [Примеры](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/ci-cd.md#examples).


##### Пример конфигурации с зависимостями между кубиками {#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 ./...
```

##### Пример конфигурации, при которой задание продолжится даже после завершения кубика ошибкой {#cubes-with-allow-failure}

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

##### Пример конфигурации с условным исполнением кубиков {#cubes-with-condition}

```yaml
workflows:
  workflow-name:
    tasks:
      - name: task-name
        cubes:
          # Кубик выполнится, только если рабочий процесс запущен в ветке, имя которой 
          # содержит текст «release», и целевая ветка в предложении изменений — «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".'

          # Кубик выполнится, только если рабочий процесс запущен в ветке, имя которой
          # содержит текст «feature», или целевая ветка в предложении изменений — не «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".'

          # Кубик выполнится вне зависимости от того, успешно ли выполнились предыдущие 
          # кубики или нет
          - name: condition-cube-3
            if: always()
            script:
              - env -i bash
```

##### Пример конфигурации кубика с запуском AI-навыка {#cubes-with-skill}

<!-- source: ru/_includes/sourcecraft/ci-cd/config-with-skill.md -->
В примере используется навык `issue-summary`, который создает саммари по задаче. Перед запуском [импортируйте навык из каталога](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/ai-skills.md#add-from-catalog). В параметре `issue_link` укажите ссылку на нужную задачу.

```yaml
workflows:
  skill-workflow:
    tasks:
      - name: skill-task
        cubes:
          - name: skill-cube
            skill: issue-summary
            with:
              issue_link: https://sourcecraft.dev/<слаг_организации>/<слаг_репозитория>/issues/<номер_задачи>
```

{% note tip %}

В одном задании можно использовать несколько кубиков с AI-навыками, а также добавлять к ним обычные кубики.

{% endnote %}
<!-- endsource: ru/_includes/sourcecraft/ci-cd/config-with-skill.md -->

## Docker-образы (image) {#image}

Блок `image` содержит параметры Docker-образа, который будет использоваться для выполнения кубика. Вы можете указать стандартное имя Docker-образа или путь в конкретном реестре.

{% note tip %}

Вместо `image` можно использовать блок [devcontainer](#devcontainer), чтобы запускать кубик в окружении, заданном спецификацией Development Container. Блоки `image` или `devcontainer` взаимоисключающие.

Если блоки `image` или `devcontainer` не указаны, команды будут выполняться в окружении Linux.

{% endnote %}

Поддерживаются следующие опциональные параметры:
* `args` — аргументы, которые будут переданы на вход контейнеру при запуске. Нельзя использовать в кубике, в котором задан параметр `script`.
* `entrypoint` — переопределение точки входа (entrypoint) контейнера. Аналог флага `--entrypoint` для команды `docker run`.

  Подробнее о работе с точкой входа и аргументами в разделе [Точка входа (entrypoint) и аргументы (args)](#entrypoint-and-args).
* `name` — путь к Docker-образу в реестре.
* `password` — пароль для доступа к реестру. Для хранения пароля рекомендуется использовать [секреты](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/index.md#secrets).
* `username` — имя пользователя для доступа к реестру.

##### Пример конфигурации Docker-образа со стандартным именем {#image-standard-name}

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

##### Пример конфигурации Docker-образа с указанием пути в конкретном реестре {#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!"
```

##### Пример конфигурации Docker-образа с аутентификацией {#image-auth}

Если для доступа к реестру нужна аутентификация, то можно использовать в задании команду `docker login` или задать настройки аутентификации в блоке `image` и задействовать [секрет](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/index.md#secrets), например:

```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.<название_секрета> }}
```

Подробнее о работе с секретами на странице [Управлять секретами в репозитории SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/secrets.md).

## Точка входа (entrypoint) и аргументы (args) {#entrypoint-and-args}

### Выполнить набор команд в Docker-контейнере {#run-commands-in-container}

Чтобы выполнить набор команд в контексте контейнера, укажите путь к Docker-образу в реестре в параметрах `image` или `image:name`, а набор команд — в `script`, например:

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

Если в контейнере переопределена точка входа, то, чтобы выполнить в нем команды из `script`, сбросьте точку входа. Это можно сделать, указав в параметре `entrypoint` значение `""`. Например, вы можете использовать контейнер, у которого по умолчанию задана точка входа `ENTRYPOINT ["/usr/bin/docker"]`:

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

### Передать аргументы командной строки в Docker-контейнер {#pass-args-to-container}

Чтобы передать в контейнер с переопределенной точкой входа аргументы, которые нужны для его выполнения, используйте параметр `args`. Например, это может быть контейнер, который используется для создания нового Docker-образа:

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

Эквивалентная конфигурация:

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

{% note tip %}

Чтобы гибко решать задания CI/CD с помощью Docker-контейнеров, комбинируйте параметры `entrypoint` и `args`.

{% endnote %}

Пример совместного использования `entrypoint` и `args`:

```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'"]
```

Эквивалентная конфигурация с помощью `script`:

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

Параметр `script: [commands]` является альтернативой установки `entrypoint: "default shell"` и `args: ["-c", 'command_1 && … && command_N']`.

{% note warning %}

В одном кубике нельзя одновременно задать `image:args` и `script`.

{% endnote %}

## Окружение Development Container (devcontainer) {#devcontainer}

Блок `devcontainer` позволяет запустить кубик в окружении, которое описано [спецификацией Development Container](https://containers.dev/implementors/spec/). При запуске кубика контейнер собирается по конфигурации из репозитория, а затем в нем выполняется команда из блока `script`.

{% note tip %}

Вместо `devcontainer` можно использовать блок [image](#image), чтобы запускать кубик в окружении конкретного Docker-образа. Блоки `image` или `devcontainer` взаимоисключающие.

Если блоки `image` или `devcontainer` не указаны, команды будут выполняться в окружении Linux. 

{% endnote %}

[Примеры спецификаций Development Container](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/spaces-env-config.md#examples)

Блок `devcontainer` обязательно должен содержать параметр `workspace_folder` — путь к директории в репозитории, в которой расположены файлы `devcontainer.json`, `Dockerfile` и прочие связанные со спецификацией файлы.

##### Пример конфигурации кубика с 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
```

В этом примере в кубике `simple-devcontainer` собирается окружение по конфигурации из директории `devcontainer_tests/simple` и выполняется команда `cargo version`.

## Переиспользование параметров кубиков {#reusable-cubes}

<!-- source: ru/_includes/sourcecraft/ci-cd/cubes-reuse.md -->
С помощью параметра `uses` в текущем кубике можно переиспользовать параметры другого кубика. В зависимости от того, где определен переиспользуемый кубик, применяется следующий синтаксис:

* `uses: <имя_кубика>` — для кубиков, определенных в `.sourcecraft/ci.yaml`. Подробнее в подразделе [Пример переиспользования параметров кубика внутри одного .sourcecraft/ci.yaml](#cubes-uses).
* `uses: ./<путь_к_файлу_в_репозитории>/cubes/<имя_кубика>` — для кубиков, определенных в произвольном YAML-файле этого же репозитория. Подробнее в подразделе [Пример переиспользования параметров кубика из произвольного YAML-файла этого же репозитория](#cubes-uses-file). Количество файлов с кубиками или количество кубиков в каждом файле не ограничено.

  {% note warning %}

  Путь должен начинаться с `./`. После пути к файлу должно быть указано `/cubes/<имя_кубика>`.

  {% endnote %}

* `uses: <слаг_организации>/<слаг_репозитория>/<путь_к_файлу_в_репозитории>/cubes/<имя_кубика>` — для кубиков, определенных в произвольном YAML-файле другого репозитория. Подробнее в подразделе [Пример переиспользования параметров кубика из произвольного YAML-файла другого репозитория](#cubes-uses-repo-file).

  {% note warning %}

  Чтобы переиспользовать кубик из другого репозитория, у этого кубика должен быть задан флаг `exported: true`. Если флаг не задан, то попытка переиспользовать кубик в другом репозитории завершится ошибкой.

  {% endnote %}

Вы можете переопределить отдельные параметры текущего кубика. Подробнее в подразделе [Пример переиспользования параметров кубика внутри одного .sourcecraft/ci.yaml](#cubes-uses).

##### Пример переиспользования параметров кубика внутри одного .sourcecraft/ci.yaml {#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
      # Переиспользование кубика с переопределением параметра
      - name: second-cube
        env:
          CUBE_VAR: world
        uses: external-cube

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

##### Пример переиспользования параметров кубика из произвольного YAML-файла этого же репозитория {#cubes-uses-file}

Файл с переиспользуемым кубиком `.ci-files/cubes/bash-lib.yaml`:

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

##### Пример переиспользования параметров кубика из произвольного YAML-файла другого репозитория {#cubes-uses-repo-file}

Файл с переиспользуемым кубиком `.ci-files/cubes/bash-lib.yaml` в другом репозитории `myrepo` организации `myorg`:

```yaml
cubes:
  - name: external-cube-1
    env:
      CUBE_VAR: hello
    script:
      - echo $CUBE_VAR
    # Флаг, разрешающий использовать кубик в других репозиториях
    exported: true
  - name: external-cube-2
    script:
      - echo "world"
    exported: true
```

Файл `.sourcecraft/ci.yaml` репозитория, в котором настраивается CI:

```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
      - name: second-task
        cubes:
          - name: second-cube
            uses: myorg/myrepo/.ci-files/cubes/bash-lib.yaml/cubes/external-cube-2
```
<!-- endsource: ru/_includes/sourcecraft/ci-cd/cubes-reuse.md -->

## Автоматический перезапуск кубика {#auto-retry}

Чтобы разрешить автоматический перезапуск кубика, установите для него параметр `retry`. Укажите в параметре максимальное количество повторных попыток и условия перезапуска.

При каждом перезапуске:

* Очищаются переменные окружения (`env`), добавленные в ходе предыдущей попытки.
* Очищаются данные, записанные в блок `outputs` в ходе предыдущей попытки.
* Артефакты, созданные в процессе выполнения кубика, сохраняются только для последней попытки, вне зависимости от ее успешности.
* Данные на файловой системе не очищаются. Необходимо самостоятельно убедиться, что данные, которые могли быть изменены, не повлияют на результаты перезапуска.
* При отмене задачи (`cancel`) механизм перезапуска блокируется, кубик не перезапускается.

Если для кубика одновременно установлены параметры `retry` и `allow_failure`, то количество перезапусков определяется параметром `retry`.

### Перезапуск по умолчанию {#retry-default}

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

В этом примере:

* `retry` — максимальное количество повторных попыток. После первого запуска кубик будет перезапущен максимум три раза.
* Условия перезапуска не указаны, поэтому перезапуск может произойти как при ошибке исполнения, так и при превышении таймаута.

### Перезапуск с условиями {#retry-conditions}

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

В этом примере:

* `max` — максимальное количество повторных попыток. После первого запуска кубик будет перезапущен максимум три раза.
* `on_error_types` — условия перезапуска:
    * `timeout` — перезапуск при превышении таймаута.

## Проверка статусов предыдущих кубиков {#check-prev-statuses}

Возможные статусы:

* `success` — успешное выполнение.
* `failure` — неуспешное выполнение: ошибка.
* `ignored_failure` — условно успешное выполнение: игнорируемая ошибка трансформируется из `failure` при включенном `allow_failure=true`.
* `timeout` — неуспешное выполнение: выполнение прервано по таймауту.
* `ignored_timeout` — условно успешное выполнение: игнорируемый таймаут трансформируется из `timeout` при включенном `allow_failure=true`.
* `skipped` — кубик пропущен: не выполнялся из-за условия `if`, вернувшего значение `false`.
* `cancelled` — кубик отменен: выполнение всего workflow было отменено пользователем.

### Проверка статуса любого предыдущего кубика {#check-any-prev-status}

Чтобы проверить статус любого предыдущего кубика, используйте в условии `if` выражение вида `cubes.<имя_кубика>.status == <статус>`.

**Пример**

```yaml
cubes:
  # Кубик 1: Успешный кубик
  - name: success-cube
    script:
      - echo "This cube must succeed"

  # Кубик 2: Проверка success статуса предыдущего кубика
  - name: if-success-cube
    if: cubes.success-cube.status == "success"
    needs:
      - success-cube
    script:
      - echo "success-cube succeeded (expected)!"
```

### Проверка сводного статуса всех предыдущих кубиков {#check-all-prev-statuses}

Чтобы проверить сводный статус всех кубиков, завершивших свою работу до текущего, используйте в условии `if` функции:

* `success()` — возвращает `true`, если все предыдущие кубики завершились успешно или почти успешно.

    Статусы, подходящие под условие:

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

* `failure()` — возвращает `true`, если хотя бы один из предыдущих кубиков завершился с ошибкой.

    Статусы, подходящие под условие:

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

**Пример**

```yaml
cubes:
# Кубик 1: Успешный кубик
- name: success-cube
  script:
    - echo "This cube must succeed"

# Кубик 2a: Проверка success статуса предыдущего кубика
- name: if-success-cube
  # if-условие проверки статуса любого предыдущего кубика
  if: cubes.success-cube.status == "success"
  needs:
    - success-cube
  script:
    - echo "success-cube succeeded (expected)!"

# Кубик 2б: Проверка failure статуса предыдущего кубика
- name: if-failure-cube
  # if-условие проверки сводного статуса по всем кубикам, завершивших свою работу до этого кубика
  if: failure() || !success()
  needs:
    - success-cube
  script:
    - echo "success-cube failed (not expected)!"
    - exit 1

# Кубик 3: Кубик с ошибкой
- name: failed-cube
  allow_failure: true
  needs:
    - if-success-cube
    - if-failure-cube
  script:
    - echo "This cube must fail"
    - exit 1

# Кубик 4а: Проверка failure статуса предыдущего кубика
- name: if-success-cube-2
  if: cubes.failed-cube.status == "success"
  needs:
    - failed-cube
  script:
    - echo "failed-cube succeeded (not expected)!"
    - exit 1

# Кубик 4б: Проверка статуса failure предыдущего кубика
- name: if-failure-cube-2
  if: cubes.failed-cube.status == "ignored_failure"
  needs:
    - failed-cube
  script:
    - echo "failed-cube failed (expected)!"
```

Статус выполнения предыдущих кубиков также можно проверить в скриптах посредством использования синтаксиса для `outputs`: `${{ cubes.<cube-name>.status }}`.

**Пример**

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

#### Полезные ссылки {#see-also}

* [Переиспользование параметров рабочих процессов и кубиков в CI/CD SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/reuse.md)
* [Передача переменных окружения от одного кубика к другому в CI/CD SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/env-vars-between-cubes.md)
* [Передача данных между заданиями CI/CD SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/data-between-tasks.md)
* [Задания (tasks)](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/tasks.md)
* [События-триггеры (on)](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/on.md)
* [Рабочие процессы (workflows)](https://sourcecraft.dev/portal/docs/ru/sourcecraft/ci-cd-ref/workflows.md)
* [Непрерывная интеграция и непрерывное развертывание в SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/ci-cd.md)
* [Настроить CI/CD в репозитории SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/ci-cd.md)
* [Управлять секретами в репозитории SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/secrets.md)
* [Работа с переменными окружения в SourceCraft](https://sourcecraft.dev/portal/docs/ru/sourcecraft/operations/variables.md)
* [Development Containers в SourceCraft Spaces](https://sourcecraft.dev/portal/docs/ru/sourcecraft/concepts/spaces-env-config.md)