Примечание
Для доступа к этой странице требуется авторизация. Вы можете попробовать войти или изменить каталоги.
Для доступа к этой странице требуется авторизация. Вы можете попробовать изменить каталоги.
Azure DevOps Services | Azure DevOps Server 2022 — Azure DevOps Server 2019
Рабочий процесс с pull request (ПР) предоставляет разработчикам возможность получать отзывы о своем коде от коллег и от автоматизированных инструментов. Средства и службы, не относящиеся к Microsoft, могут участвовать в рабочем процессе PR, используя API статуса PR . В этой статье описывается процесс создания сервера состояния для проверки PR в репозитории Git Azure DevOps Services. Дополнительные сведения о состоянии pull request см. в разделе Настройка и расширение рабочих процессов pull request со статусом.
Необходимые условия
Категория | Требования |
---|---|
Предприятие | Организация в Azure DevOps с репозиторием Git. |
Инструменты |
-
Visual Studio Code или другой редактор кода по вашему усмотрению. - Node.js. Скачивание содержит установщик, который можно запустить для установки среды выполнения Node.js на локальном компьютере. При установке Node.jsне забудьте сохранить диспетчер пакетов npm части установки, выбранной по умолчанию. |
Аутентификация | Маркер идентификатора Microsoft Entra с областью "Код (состояние") должен иметь разрешение на изменение состояния PR. Дополнительные сведения см. в разделе проверки подлинности Microsoft Entra. |
Создание базового веб-сервера с помощью Express
Действия, описанные в этом разделе, используют Express, которая представляет собой упрощенную веб-платформу для Node.js, которая предоставляет множество методов программы HTTP, упрощающих создание веб-сервера. Эта платформа предоставляет базовые функции, необходимые для прослушивания событий PR.
В командной строке создайте новую папку проекта для веб-сервера.
mkdir pr-server cd pr-server
Используйте команду
npm init
, чтобы создать новый файлpackage.json
для проекта.npm init
Выберите , затем введите, чтобы принять значения по умолчанию для всех параметров, кроме точки входа. Измените его на
app.js
entry point: (index.js) app.js
Установите Express в каталоге
pr-server
с помощью следующей команды. Это устанавливает Express и сохраняет его в списке зависимостей.npm install express
Создайте приложение Express в качестве основы для сервера отслеживания состояния PR. Следующие шаги основываются на примере Hello world (Здравствуй, мир).
a. Откройте папку проекта в Visual Studio Code, выполнив следующую команду из
pr-server
папки.code .
б. Создайте файл
(Ctrl + N)
и вставьте следующий пример кода, чтобы создать базовый сервер Express.const express = require('express') const app = express() app.get('/', function (req, res) { res.send('Hello World!') }) app.listen(3000, function () { console.log('Example app listening on port 3000!') })
с. Сохраните файл как
app.js
.Запустите базовый веб-сервер с помощью следующей команды:
node app.js
Убедитесь, что сервер запущен, перейдя по адресу
http://localhost:3000/
.
Прослушивание HTTP-запросов POST
Веб-сервер будет получать POST
запросы от Azure DevOps Services, поэтому эти запросы необходимо обрабатывать на сервере.
В конце файла
app.js
добавьте следующий код и сохраните файл.app.post('/', function (req, res) { res.send('Received the POST') })
Повторно запустите веб-сервер с помощью следующей команды:
node app.js
Настройка перехватчика службы для событий PR
Перехватчики служб — это функция Azure DevOps Services, которая может оповещать внешние службы при возникновении определенных событий. В этом примере настройте два перехватчика службы для событий PR, чтобы уведомлять сервер состояния. Первое — для события создания запроса на вытягивание, а второе — для события обновления запроса на вытягивание.
Чтобы получить уведомления о перехватчике службы, предоставьте порт для общей сети Интернет. Служебная программа ngrok полезна для этого в среде разработки.
Скачайте и распакуйте соответствующий выпуск ngrok для вашей платформы.
Используйте ngrok, чтобы начать прослушивание на том же порту, что и на вашем примере сервера — порт 3000. Выполните следующую команду в новом командном окне.
ngrok http 3000
Ngrok создает URL-адрес, который пересылает на
localhost:3000
и является общедоступным. Запишите URL-адрес, так как вам потребуется на следующем шаге. Выглядит следующим образом:http://c3c1bffa.ngrok.io
Перейдите к проекту в Azure DevOps, например
https://dev.azure.com/<your account>/<your project name>
В меню навигации наведите указатель мыши на шестеренку и выберите перехватчики службы.
Если это ваш первый сервисный хук, выберите + Создать подписку.
Если у вас уже настроены другие перехватчики служб, нажмите символ плюс
(+)
, чтобы создать новую подписку на перехватчик служб.В диалоговом окне "Новая подписка перехватчиков служб" выберите веб-перехватчики из списка служб, а затем выберите Далее.
Выберите запрос на вытягивание, созданный из списка триггеров событий, а затем выберите Далее.
На странице "Действие" введите URL из ngrok в поле URL. Выберите Test, чтобы отправить тестовое событие на сервер.
В окне консоли ngrok входящий
POST
возвращает200 OK
и указывает, что сервер получил событие хука службы.HTTP Requests ------------- POST / 200 OK
В окне "Уведомление о тестировании" выберите вкладку "Ответ", чтобы просмотреть сведения об ответе с сервера. Вы должны увидеть длину содержимого, равную 17, соответствующую длине строки из вашего обработчика POST (например, "Получен POST").
Закройте окно уведомления о тестировании и выберите Завершить, чтобы создать веб-хук службы.
Повторите шаги 3-9, но на этот раз настройте обновленный запрос на вытягивание.
Важный
Обязательно дважды выполните описанные выше действия и создайте хуки сервисов для события созданного запроса на вытягивание и события обновленного запроса на вытягивание.
Состояние публикации в PR
Теперь, когда сервер может получать события хуков при создании новых PR, обновите его, чтобы отправить статус обратно в PR.
Запросы веб-хука службы включают JSON-данные, описывающие событие. Чтобы помочь в обработке JSON, возвращаемого перехватчиком службы, установите пакет body-parser.
npm install body-parser
Обновите
app.js
, чтобы использовать body-parser для разбораapplication/json
.var bodyParser = require('body-parser') app.use(bodyParser.json())
Чтобы упростить вызовы REST API в Azure Repos, установите пакет azure-devops-node-api.
npm install azure-devops-node-api
Обновите
app.js
, чтобы использовать пакет API azure-devops-node-api, настройте сведения о подключении к учетной записи и получите экземпляр API Git.const vsts = require("azure-devops-node-api") const collectionURL = process.env.COLLECTIONURL const token = process.env.TOKEN var authHandler = vsts.getBearerHandler(token) var connection = new vsts.WebApi(collectionURL, authHandler) var vstsGit = connection.getGitApi()
Создайте переменную среды для URL-адреса коллекции, заменив
<your account>
именем организации Azure DevOps.setx COLLECTIONURL "https://dev.azure.com/<your account>"
Получите маркер идентификатора Microsoft Entra для вашего приложения. Маркеры идентификатора Microsoft Entra — это рекомендуемый метод проверки подлинности для REST API Azure DevOps. Эти маркеры можно получить следующими способами:
- Вариант 1. Azure CLI (для разработки и тестирования)
az account get-access-token --resource 499b84ac-1321-427f-aa17-267ca6975798 --query "accessToken" --output tsv
- Вариант 2: Сервисный принципал (для продукционной среды)
- Зарегистрируйте приложение в Microsoft Entra ID
- Создание секрета клиента для приложения
- Предоставление приложению соответствующих разрешений в Azure DevOps
- Используйте учетные данные служебной учетной записи для программного получения токенов
Дополнительные сведения см. в разделе проверки подлинности Microsoft Entra.
- Вариант 1. Azure CLI (для разработки и тестирования)
Создайте переменную среды для токена Microsoft Entra ID.
setx TOKEN "your-entra-id-token-here"
Получение токенов Microsoft Entra ID программно (рекомендуется для продакшн)
Для рабочих приложений следует программно получать маркеры идентификатора Microsoft Entra, а не использовать статические маркеры. Вот как реализовать эту реализацию с помощью библиотеки проверки подлинности Майкрософт (MSAL) для Node.js:
Установите пакет узла MSAL:
npm install @azure/msal-node
Создайте модуль поставщика токенов (
tokenProvider.js
):const { ConfidentialClientApplication } = require('@azure/msal-node'); const clientConfig = { auth: { clientId: process.env.CLIENT_ID, clientSecret: process.env.CLIENT_SECRET, authority: `https://login.microsoftonline.com/${process.env.TENANT_ID}` } }; const cca = new ConfidentialClientApplication(clientConfig); async function getAccessToken() { const clientCredentialRequest = { scopes: ['499b84ac-1321-427f-aa17-267ca6975798/.default'] }; try { const response = await cca.acquireTokenByClientCredential(clientCredentialRequest); return response.accessToken; } catch (error) { console.error('Error acquiring token:', error); throw error; } } module.exports = { getAccessToken };
Обновите
app.js
, чтобы использовать поставщик токенов.const { getAccessToken } = require('./tokenProvider'); // Instead of using a static token, get a fresh token app.post("/", async function (req, res) { try { const token = await getAccessToken(); var authHandler = vsts.getBearerHandler(token); var connection = new vsts.WebApi(collectionURL, authHandler); // ... rest of your POST handler code } catch (error) { console.error('Authentication error:', error); res.status(500).send('Authentication failed'); } });
Обновите функцию
post()
, чтобы прочитать сведения о PR из полезной нагрузки хука службы. Вам требуются эти значения для отправки обновления статуса.var repoId = req.body.resource.repository.id var pullRequestId = req.body.resource.pullRequestId var title = req.body.resource.title
Создайте объект состояния для публикации в PR.
State
— это перечисление типа GitStatusState. Используйтеsucceeded
, чтобы указать, что PR прошел проверку статуса и готов к объединению.description
— это строковое значение, отображающее для пользователя в разделе "Состояние" и ленте активности в представлении сведений о PR.targetUrl
— это URL-адрес, который используется для создания ссылки на текст описания в разделе "Состояние" и веб-канале действий, где пользователи могут получить дополнительные сведения о состоянии, например отчет о сборке или тестовом запуске. Если URL-адрес не указан, описание отображается как текст без ссылки.Контекст
name
иgenre
используются для классификации состояния и отличия его от других служб, публикующих состояние.var prStatus = { "state": "succeeded", "description": "Ready for review", "targetUrl": "https://visualstudio.microsoft.com", "context": { "name": "wip-checker", "genre": "continuous-integration" } }
Вместо того чтобы сразу публиковать состояние
succeeded
, проверьте заголовок PR, чтобы узнать, указал ли пользователь, что PR является работой в процессе, добавив WIP в заголовок. Если это так, измените статус, возвращённый в PR.if (title.includes("WIP")) { prStatus.state = "pending" prStatus.description = "Work in progress" }
Наконец, опубликуй состояние с помощью метода
createPullRequestStatus()
. Необходимо наличие объекта статуса, идентификатора репозитория и идентификатора пулл-реквеста. Ответ выводится на консоль узла, чтобы можно было увидеть результат отправки.vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => { console.log(result) })
Полученный метод должен выглядеть примерно так:
app.post("/", async function (req, res) { try { // Get the details about the PR from the service hook payload var repoId = req.body.resource.repository.id var pullRequestId = req.body.resource.pullRequestId var title = req.body.resource.title // Build the status object that we want to post. // Assume that the PR is ready for review... var prStatus = { "state": "succeeded", "description": "Ready for review", "targetUrl": "https://visualstudio.microsoft.com", "context": { "name": "wip-checker", "genre": "continuous-integration" } } // Check the title to see if there is "WIP" in the title. if (title.includes("WIP")) { // If so, change the status to pending and change the description. prStatus.state = "pending" prStatus.description = "Work in progress" } // Get the Git API instance and post the status to the PR const gitApi = await vstsGit const result = await gitApi.createPullRequestStatus(prStatus, repoId, pullRequestId) console.log(result) res.send("Received the POST") } catch (error) { console.error('Error processing PR status:', error) res.status(500).send('Error processing request') } })
Сохраните
app.js
и перезапустите node-приложение.node app.js
Создать новый pull request для тестирования сервера состояния
Теперь, когда ваш сервер работает и прослушивает уведомления веб-хуков, создайте pull request, чтобы протестировать его.
Начните с просмотра файлов. Измените файл readme.md в репозитории (или любой другой файл, если у вас нет readme.md).
Внесите изменения и зафиксируйте изменения в репозитории.
Обязательно зафиксируйте изменения в новой ветви, чтобы создать PR на следующем шаге.
Выберите ссылку Создать пулл-реквест.
Добавьте WIP в заголовке, чтобы проверить функциональные возможности приложения. Выберите Создать, чтобы создать pr.
После создания PR раздел состояния отображается с записью "В процессе работы", которая ссылается на URL-адрес, указанный в данных полезной нагрузки.
Обновите заголовок PR и удалите текст WIP и заметьте, что статус изменяется с В работе на Готово для проверки.