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

  • Мақала

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

Рабочий процесс запроса на вытягивание (PR) предоставляет разработчикам возможность получать отзывы об их коде от одноранговых узлов, а также от автоматизированных средств. Сторонние инструменты и службы могут участвовать в рабочем процессе pr с помощью API состояния PR. В этой статье описывается процесс создания сервера состояния для проверки PR в репозитории Git Azure DevOps Services. Дополнительные сведения о состоянии pr см. в разделе "Настройка и расширение рабочих процессов запроса на вытягивание" с состоянием запроса на вытягивание.

Необходимые компоненты

  • Организация в Azure DevOps с репозиторием Git. Если у вас нет организации, зарегистрируйтесь для отправки и совместного использования кода в бесплатных частных репозиториях Git.
  • Установите VS Code или другой редактор кода. Инструкции в этом руководстве используют VS Code, но действия в других редакторах кода аналогичны.

Установка Node.js

Чтобы установить Node.js, скачайте выпуск LTS, соответствующий вашей платформе. Скачивание содержит установщик, который можно запустить для установки среды выполнения Node.js на локальном компьютере. При установке Node.js обязательно сохраните часть диспетчера пакетов npm установки, которая выбрана по умолчанию.

Создание базового веб-сервера с помощью 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. Следующие шаги основаны на примере Express Hello world. Откройте папку проекта в VS Code, выполнив следующую команду из pr-server папки.

    code .

  5. Создайте файл (Ctrl + N) и вставьте следующий пример кода.

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

  6. Сохраните файл как app.js.

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

    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-адреса . Выберите "Тест" , чтобы отправить тестовое событие на сервер.

    Введите URL-адрес и выберите

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

    HTTP Requests
-------------

POST /                         200 OK

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

    Выберите вкладку ответа, чтобы просмотреть результаты теста

  9. Закройте окно "Уведомление о тестировании" и нажмите кнопку "Готово ", чтобы создать перехватчик службы.

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

Внимание

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

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

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

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

    npm install body-parser

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

    var bodyParser = require('body-parser')

app.use(bodyParser.json())

  3. Чтобы упростить вызовы REST API в Azure Repos, установите пакет API 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.getPersonalAccessTokenHandler(token)
var connection = new vsts.WebApi(collectionURL, authHandler)

var vstsGit = connection.getGitApi().then( 
    vstsGit => {                                    
        vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
            console.log(result);
        },
        error => {
            console.log(error);
        })
    }, 
    error => { 
        console.log(error);
    } 
);

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

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

  6. Создайте личный маркер проверки подлинности (PAT) для вашего приложения, следуя приведенным ниже инструкциям. Проверка подлинности с помощью личных маркеров доступа. Для каждой службы, используемой для доступа к учетной записи, необходимо создать новый PAT, назвав его соответствующим образом.

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

    setx TOKEN "yourtokengoeshere"

  8. Обновите функцию post() , чтобы прочитать сведения о pr из полезных данных перехватчика службы. Эти значения потребуются для отправки состояния обратной передачи.

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

  9. Создайте объект состояния для публикации на pr.

    State перечисление типа GitStatusStatusState. Используется 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"
        }
    }

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

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

  11. Наконец, опубликуй состояние с помощью createPullRequestStatus() метода. Для этого требуется объект состояния, идентификатор репозитория и идентификатор запроса на вытягивание. Выводит ответ на консоль узла, чтобы увидеть результат записи.

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

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

    app.post("/", function (req, res) {

    // 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"
    }

    // Post the status to the PR
    vstsGit.createPullRequestStatus(prStatus, repoId, pullRequestId).then( result => {
        console.log(result)
    })

    res.send("Received the POST")
})

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

    node app.js

Создание нового pr-запроса для тестирования сервера состояния

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

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

    Выберите

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

    Измените файл и выберите

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

    Введите новое имя ветви и нажмите кнопку

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

    Выберите

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

    Добавление WIP в заголовок PR по умолчанию

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

    Раздел состояния с записью

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

Next Steps

  • В этой статье вы узнали, как создать службу, которая прослушивает события PR через перехватчики служб и может публиковать сообщения о состоянии с помощью API состояния. Дополнительные сведения об API состояния запроса на вытягивание см. в документации по REST API.
  • Настройте политику ветви для внешней службы.