Кубики (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)

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

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

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

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

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

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

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

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

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

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

Примеры конфигураций 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)

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

Совет

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

Пример совместного использования 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'].

Важно

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

См. также

Предыдущая
Задания (tasks)
Следующая
Правила тарификации