Кубики (cubes)

В блоке cubes определяется перечень минимальных логических действий — кубиков, которые будут выполняться в задании.

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

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

• Нативный — выполняется напрямую на воркере.

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

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

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

  При работе из контейнера директории монтируются следующим образом:

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

  Пути указанных директорий можно получить из предопределенных переменных окружения $SOURCECRAFT_ROOT_DIRECTORY и $SOURCECRAFT_WORKSPACE соответственно.

  Docker-кубик задается с помощью параметра image, в котором указывается название Docker-образа, а также опционально логин, пароль, точка входа и аргументы.

В кубиках вы можете использовать переменные окружения, а также секреты. Для передачи переменных окружения от одного кубика к последующим в виде пар KEY=VALUE предусмотрена предопределенная переменная $SOURCECRAFT_ENV.

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

Артефакты, которые могут быть созданы в результате работы кубика, сохраняются для дальнейшего использования. Их можно скачать из конкретного кубика в секции Автоматизации репозитория в течение 14 дней.

Поддерживаются следующие параметры:

• name — имя кубика.
• script — команда, которая будет выполнена в кубике.
• needs — список кубиков, которые должны быть выполнены до выполнения текущего.
• image — (опционально) Docker-образ, который будет использоваться для выполнения кубика. Подробнее см. в подразделе image.
• env — переменные окружения, доступные только в конкретном кубике.
• artifacts — список путей к файлам, которые будут созданы в результате работы кубика и сохранены для дальнейшего использования. Артефакты можно будет скачать из конкретного кубика в секции Автоматизации репозитория в течение 14 дней.

Примеры конфигураций кубиковПримеры конфигураций кубиков

• Использование переменных, в том числе предопределенных:

  workflows:
            my-workflow:
              tasks:
                - name: 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
                      # Здесь определяются переменные, которые будут доступны только внутри кубика
                      env:
                        CUBE_ENV_VAR: This variable is available only in cube my-cube-1.
                        # Переменная, значение которой задается из секрета
                        SECRET_VAR: ${{ secrets.<название_секрета> }}
                      script:
                        - echo "$TASK_ENV_VAR"
                        - echo "$MULTILINE_VAR"
                        - echo "$CUBE_ENV_VAR"
                        - echo "$SECRET_VAR"                
                    - name: 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"
          

  Подробнее о работе с переменными окружения см. на странице Работа с переменными окружения в SourceCraft.

• Использование артефактов:

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

  Также см. пример использования артефактов для Java в разделе Примеры.

• Зависимости между кубиками:

  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-образы (image)Docker-образы (image)

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

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

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

Поддерживаются следующие опциональные параметры:

• name — путь к Docker-образу в реестре.

• username — имя пользователя для доступа к реестру.

• password — пароль для доступа к реестру. Для хранения пароля рекомендуется использовать секреты.

• entrypoint — переопределение точки входа (entrypoint) контейнера. Аналог флага --entrypoint для команды docker run.

• args — аргументы, которые будут переданы на вход контейнеру при запуске. Нельзя использовать в кубике, в котором задан параметр script.

  Подробнее о работе с точкой входа и аргументами см. в разделе Точка входа (entrypoint) и аргументы (args).

Примеры конфигураций Docker-образовПримеры конфигураций Docker-образов

• Указание стандартного имени Docker-образа:

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

• Указание пути в конкретном реестре:

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

• Если для доступа к реестру нужна аутентификация, то можно использовать в задании команду docker login или задать настройки аутентификации в блоке image и задействовать секрет, например:

  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.

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

Выполнить набор команд в Docker-контейнереВыполнить набор команд в Docker-контейнере

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

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

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

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

Передать аргументы командной строки в Docker-контейнерПередать аргументы командной строки в Docker-контейнер

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

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

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

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

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

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:

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

См. такжеСм. также

• Задания (tasks)
• События-триггеры (on)
• Рабочие процессы (workflows)
• Непрерывная интеграция и непрерывное развертывание в SourceCraft
• Настроить CI/CD в репозитории SourceCraft
• Управлять секретами в репозитории SourceCraft
• Работа с переменными окружения в SourceCraft