Настройка и расширение рабочих процессов pull-запросов с помощью статуса pull-запросов

Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019

Запросы на вытягивание — это отличный инструмент для упрощения проверки кода и управления перемещением кода в репозитории. Политики ветвления обеспечивают качество кода во время процесса pull request, определяя требования, которые должны выполняться для каждого изменения кода. Эти политики позволяют командам применять множество рекомендаций, связанных с проверкой кода и выполнением автоматизированных сборок, но многие команды имеют дополнительные требования и проверки для выполнения кода. Для удовлетворения этих индивидуальных и пользовательских требований Azure Repos предлагает состояния запроса на вытягивание. Состояния pull request интегрируются в рабочий процесс PR и позволяют внешним службам программно одобрять изменение кода, связывая простые сведения об успехе или провале с запросом на вытягивание. При необходимости pull request могут быть блокированы до тех пор, пока внешняя служба не утвердит изменение.

Предпосылки

Категория	Требования
доступ к проекту	Член проекта .
Разрешения	— Просмотр кода в частных проектах: по крайней мере базовый доступ. — Клонирование или внесение вклада в код в частных проектах: Участник группы безопасности для участников или наличие соответствующих разрешений в проекте. — Задайте разрешения ветви или репозитория: управление разрешениями для ветви или репозитория. — Измените ветвь по умолчанию: . Измените политики и разрешения для репозитория. — Импорт репозитория: член группы безопасности администраторов проекта или разрешение уровня проекта Git на создание репозитория установлено в «Разрешить» . Дополнительные сведения см. в разделе "Настройка разрешений репозитория Git".
услуги	Repos включено.
Инструменты	Необязательно. Используйте команды az repos: Azure DevOps CLI.

Примечание.

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

Интеграция в рабочий процесс pr включает несколько различных концепций:

• Состояние pull request — предоставляет службам способ связывания сведений об успешном выполнении или неудаче с pull request.
• Политика состояния — предоставляет механизм блокировки завершения pull request до тех пор, пока состояние pull request не указывает на успех.
• Пользовательские действия — это способ расширения меню состояния с помощью расширений Azure DevOps Services.

В этом разделе вы узнаете о статусах pull request'ов и о том, как их можно использовать для интеграции в workflow pull request'ов.

Статус пулл-реквеста

Статус пулл-реквеста предоставляет способ для служб связывать информацию о статусе успешного выполнения или отказа с пулл-реквестом, используя API состояния. Состояние состоит из четырех ключевых элементов данных:

• Состояние. Одно из следующих предопределенных состояний: succeeded, failed, pending, , notSetnotApplicableили error.
• Описание. Строка, описывающая состояние конечного пользователя.
• Контекст. Имя состояния— обычно описание сущности, публикующей состояние.
• URL-адрес. Ссылка, по которой пользователи могут получить дополнительные сведения о состоянии.

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

• Соответствуют ли изменения требованиям?
• Где можно узнать больше о том, что мне нужно сделать для удовлетворения требований?

Рассмотрим пример. Рассмотрим службу CI , необходимую для сборки всех изменений кода в проекте. Когда эта служба оценивает изменения в pull request, следует разместить результаты сборки и тестов. Для изменений, которые проходят сборку, на PR может быть размещён такой статус:

{
    "state": "succeeded",
    "description": "CI build succeeded",
    "context": {
        "name": "my-ci-system",
        "genre": "continuous-integration"
    },
    "targetUrl": "http://contoso.com/CI/builds/1"
}

Это состояние будет отображаться для конечного пользователя в представлении сведений о pr:

• Отображение state пользователю осуществляется с помощью значков (зелёная галочка для succeeded, красный X для failed, часы для pending и красный ! для error).
• Отображается description рядом со значком, а context доступен в подсказке.
• targetUrl При применении описание будет отображаться как ссылка на URL-адрес.

Обновление состояния

Служба может обновить статус PR для одного PR, публикуя дополнительные состояния, и только последние из этих состояний отображаются для каждого уникального context. Размещение нескольких статусов помогает пользователям управлять ожиданиями. Например, публикация pending состояния — хороший способ подтвердить пользователю, что система получила событие и начинает работу. Использование информативного description , например следующих примеров, может помочь пользователю понять, как работает система:

• "Сборка в очереди"
• "Выполняется сборка"
• "Сборка выполнена успешно"

Состояние итерации

При изменении исходной ветви в PR создается новая "итерация" для отслеживания последних изменений. Службы, которые оценивают изменения кода, хотят опубликовать новое состояние для каждой итерации PR. Размещение состояния в определенной итерации PR гарантирует, что состояние применяется только к коду, который был оценен и ни один из будущих обновлений.

Примечание.

Если создаваемый PR содержит более 100 000 измененных файлов, то по причинам производительности и стабильности этот PR не будет поддерживать итерации. Это означает, что любое дополнительное изменение в таком PR будет включено, но для этого изменения не будет создана новая итерация. Кроме того, любая попытка создать состояние для несуществующей итерации вернет ошибку.

И наоборот, если статус применяется ко всему PR, независимо от кода, публикация в итерации может быть ненужна. Например, проверка того, что автор (неизменяемое свойство PR) принадлежит определенной группе, нужно оценивать только один раз, и для этого не потребуется учитывать состояние итерации.

При настройке политики состояния, если используется состояние итерации, условия сброса должны быть заданы для состояния сброса всякий раз при наличии новых изменений. Это еще больше гарантирует, что PR не сможет быть объединен до тех пор, пока последняя итерация не имеет статуса succeeded.

Примеры REST API для размещения состояния в итерации и в пулл-реквесте.

Политика статуса

Только при использовании состояния сведения из внешней службы могут предоставляться пользователям в рамках взаимодействия с pr. Иногда предоставление информации о PR — это всё, что необходимо, но в других случаях PR следует блокировать от слияния до тех пор, пока не будут выполнены требования. Как и во встроенных политиках, политика состояния позволяет внешним службам блокировать завершение PR до тех пор, пока не будут выполнены требования. Если правило требуется, оно обязано быть выполнено, чтобы завершить пулл-реквест. Если политика необязательна, она носит только информационный характер, и для завершения запроса на вытягивание не требуется статус succeeded.

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

Если указана политика состояния, требуется, чтобы присутствовало состояние succeeded с context, соответствующее выбранному имени, для того чтобы эта политика была принята.

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

Применимость политики

Параметры применимости политики определяют, будет ли эта политика применяться сразу после создания pull request или только после публикации первого статуса в pull request.

1. Применить по умолчанию — политика применяется сразу после создания пулреквеста. Этот параметр предотвращает учет политики после создания pull request до публикации статуса succeeded. PR можно освободить от соблюдения политики, установив статус notApplicable, что приведет к удалению требования соблюдения политики.

2. Условный — политика не применяется, пока первое состояние не будет опубликовано в pull запросе.

Вместе эти параметры можно использовать для создания набора динамических политик. Политика оркестрации верхнего уровня может применяться по умолчанию при оценке pr для применимых политик. Затем, когда принимаются дополнительные условные политики (возможно, на основе конкретных выходных данных сборки), их статус может быть опубликован, чтобы они стали обязательными. Эта политика оркестрации может быть помечена succeeded, когда завершится оценка, или может быть помечена notApplicable, чтобы указать на PR, что политика не применяется.

Пользовательские действия

Помимо предопределенных событий перехватчика служб, которые могут активировать службу для обновления состояния pull request, можно расширить меню состояния с помощью расширений Azure DevOps Services, чтобы предоставить пользователю триггерные действия. Например, если состояние соответствует тестовому запуску, который может быть перезапущен конечным пользователем, можно иметь элемент меню "Перезапустить " в меню состояния, которое запускает выполнение тестов. Чтобы добавить меню состояния, необходимо использовать модель вклада. Дополнительные сведения см. в примере расширения Azure DevOps.

Дальнейшие действия

Узнайте больше об API состояния PR и ознакомьтесь с руководствами.

• Создайте сервер статусов pull-запросов с помощью Node.js
• Использование Функций Azure для создания пользовательских политик ветвей
• Настройка политики ветвей для внешней службы