Справочник для gitflic-ci.yaml файла

В этой документации перечислены ключевые слова для конфигурации вашего gitflic-ci.yaml файла

Глобальные ключевые слова

Ключевые слова Описание
image Docker Image
stages Имена и порядок выполнения этапов конвейера
cache Список файлов и каталогов для кэширования между задачами

Ключевые слова для задачи

Ключевые слова Описание
stage Определение стейджа для задачи
before_script Список шелл-скриптов которые будут выполнены агентом перед задачей
scripts Список шелл-скриптов которые будут выполнены раннером
after_script Список шелл-скриптов которые будут выполнены агентом после задачи
artifacts Список файлов и каталогов для прикрепления к задачи в случае успеха.
directory
needs Данное поле может содержать массив названий задач, которые необходимы для выполнения текущей задачи.
rules Список условий по которым можно менять некоторые поля задачи и определять, будет ли она создана.
except Название веток на которых задача не будет создана.
only Название веток на которых будет создан.
tags Теги задачи для раннера.
allow_failure Используйте allow_failure, чтобы определить, должен ли конвейер продолжать работу в случае сбоя задачи.
variables Список переменных, дополнительно объявленных для данной задачи.

Глобальные ключевые слова

image

Используйте image, чтобы указать образ Docker, в котором выполняется конвейер.

Пример:

image: maven:3.8.5-openjdk-11-slim

stages

Используйте stages, чтобы определить список этапов выполнения конвейера.

Если этапы не определены в gitflic-ci.yaml файле, то по умолчанию используются:

  • .pre
  • build
  • test
  • deploy
  • .post

Порядок элементов этапов определяет порядок выполнения задач:

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

Пример:

stages:
  - build
  - test
  - deploy
  • Все этапы выполняются друг за другом. Если какой-либо этап будет провален, то не начнется следующий и конвейер завершится с ошибкой.
  • Если все эти этапы будут успешно пройдены, то конвейер будет считаться успешно выполненным.

cache

Используйте cache, чтобы указать список файлов и каталогов для кэширования между задачами. Вы можете использовать только те пути, которые есть в локальной рабочей копии.

Кэширование распределяется между конвейерами и заданиями. Кэши восстанавливаются раньше артефактов.

cache:paths

Используйте cache:paths, чтобы выбрать файлы или каталоги для кэширования.

Пример:

cache:
  paths:
    - .m2/repository/
    - core/target/
    - desktop/target/

cache:key

Используйте cache:key, чтобы присвоить кэшу уникальный идентификационный ключ. Все задачи, использующие один и тот же ключ кэша, используют один и тот же кэш.

Если не задано, по умолчанию используется ключ default. Все задания с cache ключевым словом, но без cache:key совместного использования default кеша.

Должен использоваться с cache:paths, иначе ничего не кэшируется.

cache:when

Используется cache:when для определения времени сохранения кэша в зависимости от состояния задачи.

Должен использоваться с cache:paths, иначе ничего не кэшируется.

Возможные значения:

  • on_success(по умолчанию): Сохранять кеш только после успешного выполнения задачи.
  • on_failure: Сохранять кеш только в случае сбоя задачи.
  • always: всегда сохранять кеш.

Пример:

cache:
  paths:
    - .m2/repository/
    - core/target/
    - desktop/target/

Ключевые слова для задачи

stage

Используйте stage, для определения этапа для задачи.

Пример


stages:
  - build
  - deploy
  
job 0:
  stage: build

scripts

Используйте scripts, чтобы указать команды для выполнения раннером.

job1:
  scripts: apt-get update

job2:
  scripts:  
      - apt-get -y install maven
      - apt-get -y install git

before_script

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

Тип ключевого слова: Ключевое слово для задачи. Вы можете использовать его только как часть задачи или в разделе по умолчанию.

Возможные значения: Массив строк

Пример

job1:
  script: apt-get update
  before_script:
    - apt-get -y install maven
    - apt-get -y install git

Дополнительные сведения:

  • Сценарии, указанные в before_script, объединяются с любыми сценариями, указанными в script. Объединённые сценарии выполняются вместе в одной оболочке.

after_script

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

Тип ключевого слова: Ключевое слово для задачи. Вы можете использовать его только как часть задачи или по умолчанию во всем конвейерее.

Возможные значения: Массив строк:

Пример

job1:
  script: apt-get update
  after_script:
    - apt-get update
    - apt-get -y install maven
    - apt-get -y install git

Дополнительные сведения:

Если время ожидания задачи истекло или она была отменёна, команды after_script не выполняются.

По умолчанию используются внешние before_script и after_script shell-скрипты, однако задача может иметь и свои собственные.

Если они не определены внутри задачи, то используются внешние.

Пример


image: test

stages:
  - test

job 0:
  stage: test
  scripts:
    - mvn test
  rules:
    - if: "predicate1 && predicate2"
      when: newer

artifacts

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

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

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

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

artifacts:paths

Пути относятся к каталогу проекта и не могут напрямую ссылаться за его пределы.

Тип ключевого слова: Ключевое слово для задачи. Вы можете использовать его только как часть задачи или в разделе по умолчанию.

Возможные значения:

  • Массив путей к файлам относительно каталога проекта.

Пример


artifacts:
    paths:
      - bin/usr/
      - bin/path
      - frontend/saw

artifacts:exclude

Используйте artifacts:exclude, чтобы предотвратить добавление файлов в архив артефактов.

Тип ключевого слова: Ключевое слово для задачи. Вы можете использовать его только как часть задачи или в разделе по умолчанию.

Возможные значения:

  • Массив путей к файлам относительно каталога проекта.

Пример


artifacts:
  exclude:
    - binaries/**/*.o

Данный пример сохраняет все файлы в binaries/, исключая *.o файлы, находящиеся в дочерних директориях binaries/.

needs

Данное поле может содержать массив названий задач, которые необходимы для выполнения текущей задачи.

Пример


job-0:
  stage: test
  script: echo "Running job 0"

job-1:
  stage: test
  needs: job-0
  script: echo "Running job 1..."

rules

Используйте rules чтобы управлять созданием задач и изменять значения их полей на основе логических выражений.

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

rules являются альтернативой ключевым словам only/except и не могут быть использованы вместе с ними. Если у задачи указаны как rules, так и only и/или except, то обработка конвейера завершится с ошибкой.

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

Правило из rules является истинным, если поле if или отсутствует, или представляет собой истинное логическое выражение.

Задача будет создана, если:

  • rules не объявлены или представляют собой пустой массив.
  • Первое по порядку истинное правило имеет when не never.

Задача не будет создана, если:

  • Ни одно из правил в rules не является истинным.
  • Первое по порядку истинное правило имеет when: never.

rules:if

Используйте rules:if чтобы определять, при каких условиях правило будет истинно.

Возможные значения

Сравнение переменной со строкой

Вы можете использовать операторы равенства == и != для сравнения переменной со строкой. Допустимы как одинарные ', так и двойные " кавычки. Порядок операндов не имеет значения, поэтому переменная может быть первой, или строка может быть первой. Например:

  • if: $VAR == "string"
  • if: $VAR != "string"
  • if: "string" == $VAR
Сравнение двух переменных

Вы можете сравнивать между собой значения двух переменных. Например:

  • if: $VAR1 == $VAR2
  • if: $VAR1 != $VAR2
Проверка переменной на существование

Вы можете сравнивать значение переменной с null:

  • if: $VAR == null
  • if: $VAR != null

Вы можете сравнивать значение переменной с пустой строкой:

  • if: $VAR == ""
  • if: $VAR != ""

Вы можете проверять переменную на существование:

  • if: $VAR

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

Сравнение переменной с regex pattern

Вы можете выполнять сопоставление регулярного выражений со значением переменной с помощью операторов = ~ и !~. Для регулярных выражений используется синтаксис RE2. Регулярное выражение должно быть обернуто в символы косой черты /.

Сопоставление является истинным, если:

  • Оператор =~: найдена хотя бы одна подстрока, полностью удовлетворяющая регулярному выражению.
  • Оператор !~: не найдено ни одной подстроки, полностью удовлетворяющей регулярному выражению.

Примеры:

  • if: $VAR =~ /^feature/
  • if: $VAR !~/^feature/

Первое выражение будет истинным для значения переменной: "feature/rules/if" и ложен для "base/feature". Второе выражение для первого значения будет ложным, а для второго - истинным.

Примечание: односимвольные регулярные выражения (такие как /./) не поддерживаются и вызывают ошибку.

В качестве правого операнда может выступать другая переменная, её значение будет интерпретировано как регулярное выражение. Например:

  • if: $VAR =~ $REGEX_VAR
  • if: $VAR !~ $REGEX_VAR

Примечание: если значение переменной не обернуто в /, оно будет интерпретировано как обернутое (например, для REGEX_VAR: "^feature" результат будет аналогичен REGEX_VAR: "/^feature/").

Комбинация атомарных выражений

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

  • $VAR1 =~ /^feature/ && $VAR2 == "two"
  • $VAR1 || $VAR2 != "three" && $VAR3 =~ /main$/
  • $VAR1 AND $VAR2
  • $VAR1 OR $VAR2

Выражения можно группировать с помощью ( и ):

  • $VAR1 && ($VAR2 == "something" || $VAR3 == "something else")

Логические связки и ( ) имеют следующий приоритет выполнения:

  • Выражение в скобках.
  • Конъюнкция выражений - && или AND.
  • Дизъюнкция выражений - || или OR.

Пример

job:
  script: echo "This job uses rules!"
  variables:
    VAR1: "one"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      when: never
    - if: $CI_COMMIT_REF_NAME =~ /^feature/ && VAR1 == "one"
      allow_failure: true
      variables:
        VAR1: "one from rule"
        VAR2: "two from rule"
    - if: $CI_COMMIT_TAG
    - when: manual

Для данной задачи определены четыре правила:

  1. Первое правило будет истинно, если конвейер создается на дефолтной ветке для проекта(например main или master).
  2. Второе правило будет истинно если конвейер создается на ветке, название которой начинается с feature и внутри переменной VAR1 лежит строка one.
  3. Третье правило будет истинно если переменная CI_COMMIT_TAG объявлена.
  4. Четвертое правило всегда истинно.

Если первое правило оказалось истинным, задача не будет создана, так как when: never.

Если второе правило оказалось истинным, а первое ложным, то задача будет создана. Поле allow_failure для задачи станет true, переменная VAR1 будет перезаписана, переменная VAR2 будет добавлена к задаче, значение поля when задачи изменено не будет.

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

Если ни одно из предыдущих правил не оказалось истинным, четвертое правило поменяет значение поля when задачи на manual.

CI/CD переменные

Использование правил неразрывно связано с CI/CD переменными. На данный момент в конфигурации конвейера (и его задач) можно использовать переменные из следующих источников:

  • Объявленные через UI в настройках CI/CD для проекта. Такие переменные можно маскировать, не давая отображать их значения в логах, что повышает безопасность.
  • Предопределенные переменные.
  • Глобальные переменные, объявленные в поле variables для конвейера. Такие переменные доступны всем задачам данного конвейера.
  • Переменные, объявленные в поле variables для задачи. Такие переменные доступны только той задаче, внутри которой они объявлены.

Примечания:

Предопределенные CI/CD переменные
Имя переменной Описание
CI_PROJECT_URL URL проекта, для которого создан конвейер (например https://gitflic.ru/project/someuser/some-project-name).
CI_PROJECT_TITLE Название проекта, отображающееся в UI (например Some Project Name).
CI_PROJECT_NAME Название директории проекта (например some-project-name).
CI_PROJECT_VISIBILITY Строка private или public, в зависимости от публичности проекта.
CI_DEFAULT_BRANCH Стандартная ветка для проекта (например master).
GITFLIC_USER_EMAIL Email инициатора запуска конвейера.
GITFLIC_USER_LOGIN Юзернейм инициатора запуска конвейера.
CI_COMMIT_REF_NAME Название ветки, на которой запускается конвейер (например feature/rules).
CI_COMMIT_SHA Полный хэш коммита, на котором запускается конвейер.
CI_COMMIT_TAG Объявлена и равна строке true если конвейер запускается на теге, не объявлена если нет.
CI_PIPELINE_ID UUID конвейера.
CI_PIPELINE_IID Локальный для проекта ID конвейера, уникален на уровне проекта.
Порядок перезаписи CI/CD переменных

Значение приоритета перезаписи для различных источников переменных следующий (от наибольшего к наименьшему):

  1. Переменные, объявленные для проекта через UI.
  2. Переменные, объявленные для задачи в конфиг файле.
  3. Глобальные переменные, объявленные для конвейера в конфиг файле.
  4. Предопределенные переменные.

Переменные с равным приоритетом перезаписывают друг друга.

Пример

  • Для проекта через UI объявлена маскированная переменная POPULAR_VAR со значением Popular from project.
  • В поле variables для конвейера объявлена переменная с таким же именем, но другим значением: POPULAR_VAR: "Popular from pipeline", а также переменная OBSCURE_VAR: "Obscure from pipeline".
  • В поле variables для задачи job 0 объявлены обе эти переменные, со следующими значениями: POPULAR_VAR: "Popular from job 0", OBSCURE_VAR: "Obscure from job 0".
  • В конечном итоге получим, что для задачи job 0 значения вышеописанных переменных будут следующими: POPULAR_VAR будет равна Popular from project и маскированна, а OBSCURE_VAR будет равна Obscure from job 0.
  • Получим, что для переменной POPULAR_VAR ни значение из задачи, ни значение из конвейера не перезаписало значение, объявленное через UI для проекта. При этом значение переменной, объявленной в конвейере (OBSCURE_VAR), для задачи job 0 было перезаписано.

rules:allow_failure

При истинности правила, если это поле определено, перезаписывает значение поля allow_failure задачи.

rules:variables

При истинности правила, если это поле определено, добавляет переменные в задачу, потенциально перезаписывая уже объявленные.

Возможные значения

  • Набор полей формата VARIABLE_NAME: "variable value".

Пример

job:
  variables:
    ARGUMENT: "default"
  rules:
    - if: $CI_COMMIT_REF_NAME == $CI_DEFAULT_BRANCH
      variables:                              # Перезаписываем значение
        ARGUMENT: "important"                 #   существующей переменной
    - if: $CI_COMMIT_REF_NAME =~ /feature/
      variables:
        IS_A_FEATURE: "true"                  # Определяем новую переменную
  script:
    - echo "Run script with $ARGUMENT as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

rules:when

При истинности правила, если это поле определено, перезаписывает значение поля when задачи.

Возможные значения

  • manual - задача выполняется только при ручном запуске из UI.
  • on_failure - задача выполняется, если задача с allow_failure: false завершилась с ошибкой.
  • on_success (значение по умолчанию) - задача выполняется, только если все задачи с allow_failure: false выполнились успешно.

tags

Используйте tags для настройки раннера.

Вы можете указать теги для определенного раннера в настройках раннера

Возможные значения

  • Массив названий тегов
job:
  tags:
    - java
    - postgres

allow_failure

Используйте allow_failure, чтобы определить, должен ли конвейер продолжать работу в случае сбоя задания.

  • Чтобы конвейер продолжал выполнять последующие задачи, используйте allow_failure: true.

  • Чтобы запретить конвейеру выполнение последующих задачи, используйте allow_failure: false.

Возможные значения:

  • true
  • false (значение по умолчанию)

except

Используйте except чтобы указать ветки на которых задача не будет создана.

Возможные значения

  • Массив названий веток
job:
  except:
    - master
    - deploy

only

Используйте only чтобы указать ветки на которых будет работать задача.

Возможные значения

  • Массив названий веток
job:
  only: 
    - master

variables

Используйте variables чтобы объявить дополнительные CI/CD переменные для данной задачи.

Возможные значения

  • Имя переменной может содержать только цифры, латинские буквы и нижние подчеркивания (_).
  • Значение переменной должно быть строкой (обернуто в одинарные ' или двойные " кавычки).

Пример

job:
  script:
    - echo "this job has no additional variables"

job_with_variables:
  variables:
    VAR: "/variable"
  script:
    - echo $VAR

Примечания

  • Переменные, определенные в YAML файле являются публично видимыми, в них небезопасно определять чувствительную информацию. Объявляйте переменные, значения которых не должны быть публичны, через вкладку CI/CD в настройках проекта.
Навигация