Кубики (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 — команда, которая будет выполнена в кубике.

• uses — параметр, с помощью которого в текущем кубике можно переиспользовать параметры из другого кубика. При этом отдельные параметры текущего кубика вы можете переопределить. Подробнее см. Пример переиспользования параметров кубика.

• needs — список кубиков, которые должны быть выполнены до выполнения текущего.

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

• env — переменные окружения, доступные только в конкретном кубике. Подробнее см. Пример конфигурации кубиков с использованием переменных, в том числе предопределенных.

  Совет

  Также вы можете задать переменные окружения внутри следующих блоков:

  • workflows — переменные будут доступны во всех кубиках всех заданий конкретного рабочего процесса.
  • tasks — переменные будут доступны во всех кубиках конкретного задания.

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

Пример конфигурации кубиков с использованием переменных, в том числе предопределенных

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.<название_секрета> }}
            script:
              - echo "$TASK_ENV_VAR"
              - echo "$MULTILINE_VAR"
              - echo "$CUBE_ENV_VAR"
              - echo "$SECRET_VAR"
              - echo "$WORKFLOW_VAR"

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

      - name: my-task-2
        cubes:
          - name: my-cube-3
            script:
              - echo "$WORKFLOW_VAR"

Подробнее о предопределенных переменных см. на странице Предопределенные переменные окружения, о работе с переменными окружения — на странице Работа с переменными окружения в 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 ./...

Пример переиспользования параметров кубика

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

tasks:
  - name: the-task
    cubes:
      - name: the-cube
        uses: external-cube

workflows:
  the-workflow:
    tasks:
      - the-task

Docker-образы (image)

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

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

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

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

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

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

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

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

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

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

Пример конфигурации Docker-образа со стандартным именем

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

Пример конфигурации Docker-образа с указанием пути в конкретном реестре

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

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

Если для доступа к реестру нужна аутентификация, то можно использовать в задании команду 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)

Выполнить набор команд в 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-контейнер

Чтобы передать в контейнер с переопределенной точкой входа аргументы, которые нужны для его выполнения, используйте параметр 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