Создайте сервер состояния запроса на вытягивание с помощью Node.js

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.

1. В командной строке создайте новую папку проекта для веб-сервера.

   mkdir pr-server
   cd pr-server
   

2. Используйте команду npm init, чтобы создать новый файл package.json для проекта.

   npm init
   

   Выберите , затем введите, чтобы принять значения по умолчанию для всех параметров, кроме точки входа. Измените его на app.js

   entry point: (index.js) app.js
   

3. Установите Express в каталоге pr-server с помощью следующей команды. Это устанавливает Express и сохраняет его в списке зависимостей.

   npm install express
   

4. Создайте приложение 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.

5. Запустите базовый веб-сервер с помощью следующей команды:

   node app.js
   

   Убедитесь, что сервер запущен, перейдя по адресу http://localhost:3000/.

Прослушивание HTTP-запросов POST

Веб-сервер будет получать POST запросы от Azure DevOps Services, поэтому эти запросы необходимо обрабатывать на сервере.

1. В конце файла app.js добавьте следующий код и сохраните файл.

   app.post('/', function (req, res) {
       res.send('Received the POST')
   })
   

2. Повторно запустите веб-сервер с помощью следующей команды:

   node app.js
   

Настройка перехватчика службы для событий PR

Перехватчики служб — это функция Azure DevOps Services, которая может оповещать внешние службы при возникновении определенных событий. В этом примере настройте два перехватчика службы для событий PR, чтобы уведомлять сервер состояния. Первое — для события создания запроса на вытягивание, а второе — для события обновления запроса на вытягивание.

Чтобы получить уведомления о перехватчике службы, предоставьте порт для общей сети Интернет. Служебная программа ngrok полезна для этого в среде разработки.

1. Скачайте и распакуйте соответствующий выпуск ngrok для вашей платформы.

2. Используйте ngrok, чтобы начать прослушивание на том же порту, что и на вашем примере сервера — порт 3000. Выполните следующую команду в новом командном окне.

   ngrok http 3000
   

   Ngrok создает URL-адрес, который пересылает на localhost:3000и является общедоступным. Запишите URL-адрес, так как вам потребуется на следующем шаге. Выглядит следующим образом:

   http://c3c1bffa.ngrok.io
   

3. Перейдите к проекту в Azure DevOps, например https://dev.azure.com/<your account>/<your project name>

4. В меню навигации наведите указатель мыши на шестеренку и выберите перехватчики службы.

   

5. Если это ваш первый сервисный хук, выберите + Создать подписку.

   

   Если у вас уже настроены другие перехватчики служб, нажмите символ плюс (+), чтобы создать новую подписку на перехватчик служб.

   

6. В диалоговом окне "Новая подписка перехватчиков служб" выберите веб-перехватчики из списка служб, а затем выберите Далее.

   

7. Выберите запрос на вытягивание, созданный из списка триггеров событий, а затем выберите Далее.

   

8. На странице "Действие" введите URL из ngrok в поле URL. Выберите Test, чтобы отправить тестовое событие на сервер.

   

   В окне консоли ngrok входящий POST возвращает 200 OKи указывает, что сервер получил событие хука службы.

   HTTP Requests
   -------------
   
   POST /                         200 OK
   

   В окне "Уведомление о тестировании" выберите вкладку "Ответ", чтобы просмотреть сведения об ответе с сервера. Вы должны увидеть длину содержимого, равную 17, соответствующую длине строки из вашего обработчика POST (например, "Получен POST").

   

9. Закройте окно уведомления о тестировании и выберите Завершить, чтобы создать веб-хук службы.

Повторите шаги 3-9, но на этот раз настройте обновленный запрос на вытягивание.

Важный

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

Состояние публикации в PR

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

1. Запросы веб-хука службы включают JSON-данные, описывающие событие. Чтобы помочь в обработке JSON, возвращаемого перехватчиком службы, установите пакет body-parser.

   npm install body-parser
   

2. Обновите app.js, чтобы использовать body-parser для разбора application/json.

   var bodyParser = require('body-parser')
   
   app.use(bodyParser.json())
   

3. Чтобы упростить вызовы REST API в Azure Repos, установите пакет azure-devops-node-api.

   npm install azure-devops-node-api 
   

4. Обновите 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()
   

5. Создайте переменную среды для URL-адреса коллекции, заменив <your account> именем организации Azure DevOps.

   setx COLLECTIONURL "https://dev.azure.com/<your account>"
   

6. Получите маркер идентификатора 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: Сервисный принципал (для продукционной среды)
     1. Зарегистрируйте приложение в Microsoft Entra ID
     2. Создание секрета клиента для приложения
     3. Предоставление приложению соответствующих разрешений в Azure DevOps
     4. Используйте учетные данные служебной учетной записи для программного получения токенов

   Дополнительные сведения см. в разделе проверки подлинности Microsoft Entra.

7. Создайте переменную среды для токена Microsoft Entra ID.

   setx TOKEN "your-entra-id-token-here"
   

Получение токенов Microsoft Entra ID программно (рекомендуется для продакшн)

Для рабочих приложений следует программно получать маркеры идентификатора Microsoft Entra, а не использовать статические маркеры. Вот как реализовать эту реализацию с помощью библиотеки проверки подлинности Майкрософт (MSAL) для Node.js:

1. Установите пакет узла MSAL:

   npm install @azure/msal-node
   

2. Создайте модуль поставщика токенов (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 };
   

3. Обновите 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');
       }
   });
   

4. Обновите функцию post(), чтобы прочитать сведения о PR из полезной нагрузки хука службы. Вам требуются эти значения для отправки обновления статуса.

   var repoId = req.body.resource.repository.id
   var pullRequestId = req.body.resource.pullRequestId
   var title = req.body.resource.title
   

5. Создайте объект состояния для публикации в 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"
           }
       }
   

6. Вместо того чтобы сразу публиковать состояние succeeded, проверьте заголовок PR, чтобы узнать, указал ли пользователь, что PR является работой в процессе, добавив WIP в заголовок. Если это так, измените статус, возвращённый в PR.

       if (title.includes("WIP")) {
           prStatus.state = "pending"
           prStatus.description = "Work in progress"
       }
   

7. Наконец, опубликуй состояние с помощью метода createPullRequestStatus(). Необходимо наличие объекта статуса, идентификатора репозитория и идентификатора пулл-реквеста. Ответ выводится на консоль узла, чтобы можно было увидеть результат отправки.

   vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
       console.log(result)
   })
   

8. Полученный метод должен выглядеть примерно так:

   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')
       }
   })
   

9. Сохраните app.js и перезапустите node-приложение.

   node app.js
   

Создать новый pull request для тестирования сервера состояния

Теперь, когда ваш сервер работает и прослушивает уведомления веб-хуков, создайте pull request, чтобы протестировать его.

1. Начните с просмотра файлов. Измените файл readme.md в репозитории (или любой другой файл, если у вас нет readme.md).

   

2. Внесите изменения и зафиксируйте изменения в репозитории.

   

3. Обязательно зафиксируйте изменения в новой ветви, чтобы создать PR на следующем шаге.

   

4. Выберите ссылку Создать пулл-реквест.

   

5. Добавьте WIP в заголовке, чтобы проверить функциональные возможности приложения. Выберите Создать, чтобы создать pr.

   

6. После создания PR раздел состояния отображается с записью "В процессе работы", которая ссылается на URL-адрес, указанный в данных полезной нагрузки.

   

7. Обновите заголовок PR и удалите текст WIP и заметьте, что статус изменяется с В работе на Готово для проверки.

Связанные статьи

• документация по REST API
• Настройка политики ответвления для внешнего сервиса