Справочник для `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`	Список переменных, дополнительно объявленных для данной задачи.
`include`	Включение в конфигурацию внешних .yaml файлов.

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

`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:
  scripts: apt-get update
  before_script:
    - apt-get -y install maven
    - apt-get -y install git

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

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

`after_script`

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

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

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

Пример

job1:
  scripts: 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
  scripts: echo "Running job 0"

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

`rules`

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

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

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

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

if
allow_failure
variables
when

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

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

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

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

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

`rules:if`

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

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

Выражение с CI/CD переменными, а именно:

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

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

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:
  scripts: 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

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

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

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

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

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

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

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

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

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

Примечания:

Если переменная с одним и тем же именем объявлена в разных местах, значение будет перезаписано в соответствии с приоритетом перезаписи источников CI/CD переменных.

Предопределенные 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 переменных

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

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

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

Пример

Для проекта через 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"                  # Определяем новую переменную
  scripts:
    - echo "Run script with $ARGUMENT as an argument"
    - echo "Run another script if $IS_A_FEATURE exists"

Имя переменной	Значение	Результат
`GIT_STRATEGY`	`none`	Отключение клонирования репозитория
`GIT_STRATEGY`	Любое, кроме `none`	Применяется `git fetch`
`ARTIFACT_DOWNLOAD_STRATEGY`	`none`	Отключение скачивания артефакта

`rules:when`

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

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

never - задача не будет добавлена в конвейер
manual - задача выполняется только при ручном запуске из UI.
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:
  scripts:
    - echo "this job has no additional variables"

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

Примечания

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

`include`

Вы можете использовать include для включения внешних файлов YAML в ваши задания CI/CD.

Пример:

Для проектов

include:
  - project:
      project_path: 'my-group/my-project'
      ref: v1.0.0
      file:
        - '/templates/.gitlab-ci-template.yml'
  - project:
      project_path: 'my-group/my-project'
      ref: v1.0.0
      file:
        - '/templates/.ci-template.yml'

Для локальных файлов в репозитории

  - local:
      - "gitflic-1.yaml"
      - "gitflic-2.yaml"

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

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

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

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

image

stages

cache

cache:paths

cache:key

cache:when

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

stage

scripts

before_script

after_script

artifacts

artifacts:paths

artifacts:exclude

needs

rules

rules:if

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

Сравнение двух переменных

Проверка переменной на существование

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

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

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

Предопределенные CI/CD переменные

Порядок перезаписи CI/CD переменных

rules:allow_failure

rules:variables

rules:when

tags

allow_failure

except

only

variables

include

Навигация

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

`image`

`stages`

`cache`

`cache:paths`

`cache:key`

`cache:when`

`stage`

`scripts`

`before_script`

`after_script`

`artifacts`

`artifacts:paths`

`artifacts:exclude`

`needs`

`rules`

`rules:if`

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

`rules:allow_failure`

`rules:variables`

`rules:when`

`tags`

`allow_failure`

`except`

`only`

`variables`

`include`