Политики approvers.yml

Политики в Gitlab — это ограничения, которые помогают выстроить процесс работы над кодом вашего проекта.

Например, с помощью правила в approvers.yml вы можете контролировать, кто из пользователей может согласовать merge request. Если вы работаете во внешнем продукте, все изменения в коде должен проверять опытный разработчик или руководитель, а не стажёр или аналитик.

Правило Approve — определяет состав и количество членов команды, которые должны одобрить предлагаемые изменения в коде проекта. Оно лежит в файле approvers.yml.

Важно

Действуют только правила Approve из ветки master.

Используйте только расширение .YML.

Пример простой политики

Чтобы базово настроить политику:

1. Откройте файл approvers.yml в репозитории или создайте его.

2. Создайте правило и впишите туда код с информацией о тех, кто сможет ставить Approve. Обязательные атрибуты:

   • первая строка, например, primary-reviewers - имя правила, оно появится на виджете страницы merge request;
   • count — количество аппрувов, чтобы выложить изменения;
   • users или groups — люди, которые смогут согласовать изменения.

Лучше не использовать users. Чтобы не редактировать списки пользователей в каждом репозитории вручную, добавь их в группу и используйте groups.

В примере ниже для изменения нужен Approve от одного человека, поставить его могут t.malevinskaya и сотрудники из группы team-approvers.

primary-reviewers:
  count: 1
  users:
    - 't.malevinskaya@tbank.ru'
  groups:
    - 'team-approvers'

Также вы можете настроить и другие правила.

Некоторые настройки merge request в policy.yml тоже влияют на поведение правил Approve:

• allow_author_approval — разрешить автору аппрувить свои merge request;
• allow_commit_skip_approvals — разрешить merge request без Approve.

Файл с политикой

policy и custom-rule-1 в примерах — это названия политик. Они могут быть любыми, только называйте их понятно.

Если у вас регулярное выражение, используйте синтаксис RE2.

• можно использовать negative lookahead;
• в начале и конце используйте "^" и "$".

approvers.yml

/* 
 * Пример статических правил:
**/ 

policy:
  type: 'static'
  count: 1  
  groups:
  - example-group
  files:
  - 'policy.yml'
  target_branch: 'master'
 

  /* 
 * Пример динамических правил:
**/  
 
custom-rule-1:
  type: 'dynamic'
  enabled_by_default: true
  count: 1  
  groups:
  - example-group  
  default_reviewers:
    all_eligible: true # добавляем всех апруверов в reviewers
  default_assignees:
    groups:
    - devplatform-support   # любые группы Spirit, не обязательно из апруверов custom-rule-2:
  type: 'dynamic'
  count: 1

Атрибуты политик:

custom-rule-1:
  type: 'dynamic'
  enabled_by_default: true
  count: 1  
  groups:
  - 'my-group'
  - 'their-group'
  files:
  - 'policy.yml'

type

Тип данных: String.

Значения:

• static — статичное правило — применяется, если подходит под условия фильтров files, target_branch и source_branch.

• dynamic — динамическое правило] — его состояние можно определять для конкретного merge request.

  Его атрибут [enabled_by_default] определяет начальное состояние правила. Вы можете его включать и выключать:

  • true — включено;
  • false — выключено. Для этого у вас должна быть роль Project lead. Также можно управлять правилами через CLI Spirit(функционал не доступе).

Если type не указан, правило статично.

enabled_by_default

Тип данных: Boolean.

Применимо только к правилам type: и dynamic.

Чтобы правило было включено сразу при открытии merge request, укажите значение true.

count

Тип данных: Integer.

Количество людей, которые должны поставить Approve.

groups

Тип данных: Array[String].

Группы Devplatform, члены которых должны поставить Approve.

files

Тип данных: Array[String].

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

policy:
  ...  
  target_branch: ".*"
  source_branch: ".*"
  default_reviewers:
    all_eligible: true
  default_assignees:
    all_eligible: true

source_branch

Тип данных: String.

Регулярное выражение. Применяется к имени ветки, из которой делается merge request.

target_branch

Тип данных: String.

Регулярное выражение. Применяется к имени ветки, в которую делается merge request

default_reviewers

Тип данных: Object.

Описывает правило назначения reviewers.

Применяется однократно:

• для статичных правил — когда открывается merge request;
• для динамических правил — когда его включается.

Пользователь с ролью Gitlab developer может переопределить состав ревьюеров, если отредактировать merge request.

all_eligible:

• true — все аппруверы добавляются в reviewers. Не сработает, если указаны массивы groups или users.

groups — список групп Spirit, участников которых нужно включить в reviewers.

default_assignees

Тип данных: Object.

Работает аналогично default_reviewers.

Включить динамические правила

Динамическое — правило, состояние которого можно определять для конкретного merge request. Используйте их, когда хотите получить Approve в зависимости от изменений кода, которые нельзя описать фильтрами files, source_branch, target_branch.

Правила Approve

Вы можете включать и выключать динамические правила Approve.

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

• специфичные сетевые доступы;
• вы выделили больше ресурсов, чем в ваших лимитах.

Чтобы получить все изменения в merge request, выполните команду:

git diff <target_branch>

Включить правило

Вы можете включить или отключить правила Approve merge request с помощью утилиты Spirit CLI (функционал не доступен). Для этого у вас должна быть роль Project lead или MR custom approval rules.

Например, вы можете добавить job, в котором проанализируете изменения, и примете решение — применять ли правило Approve.

Как управлять правилами

Чтобы управлять динамическими правилами из CI, используйте Сервис-аккаунты. Примеры настройки динамических правил в CI.

В Gitlab есть предопределенные Environment variables, с ними будет проще управлять правилами:

• CI_MERGE_REQUEST_PROJECT_PATH — путь к репозиторию;
• CI_MERGE_REQUEST_IID — внутренний идентификатор merge request, он уникален в рамках репозитория;
• CI_MERGE_REQUEST_TARGET_BRANCH_NAME — имя целевой ветки, чтобы посмотреть изменения.

Они доступны только для пайплайнов, которые запустили в merge request. Добавьте в .gitlab-ci.yml для stage-атрибута:

only:
    - merge_requests

О пайплайнах в ветке и merge request

В Gitlab два типа пайплайнов, они отличаются контекстом запуска:

• branch pipeline — запущен в ветке;
• merge request pipeline — запущен в merge request.

В конфигурации gitlab-ci.yaml вы можете указать, в какой пайплайн они попадут.

Не нашёлся владелец кода

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

Например, команда «a» может аппрувить изменения только в папке projectA, а команда «b» — в projectB.

approvers.yml

team of project a:
    count: 1   
    groups:
    - 'project-a-group'   
    files:
    - 'projectA\/.*'
team of project b:
    count: 1      
    groups:
    - 'project-b-group'    
    files:
      - 'projectB\/.*'

Если в проекте есть ничьи или общие файлы, добавьте исключающее правило — оно сработает, если остальные не пройдут по условиям. Чтобы они правильно работали, добавьте «.*» перед символом окончания строки «$». Синтаксис — ^(?!(<path1>|<path2>)\/).*$.

Например, если код не лежит в папках команд, его могут аппрувить обе команды.

approvers.yml

maintainer:
    count: 1      
    groups:
    - 'project-maintainers-group'    
    files:
      - '^(?!(projectA|projectB)\/).*$'

Аппрувер недоступен

Если аппрувер один и недоступен:

1. Обратитесь в поддержку Spirit.
2. Напишите в описании, что хотите удалить файл approvers.yml.

Если в списке approvers.yml указано 2 человека — первый недоступен, второй открыл merge request:

1. Попросите коллегу не из списка его переоткрыть.
2. Второй из списка поставит Approve.