Оптимизация создания журнала изменений с помощью Azure DevOps и Confluence

В быстро меняющемся мире разработки программного обеспечения ведение подробного учета изменений имеет решающее значение. Журналы изменений служат жизненно важным инструментом, отслеживающим каждое обновление, исправление или функцию, добавленную в проект. Интеграция Azure DevOps с Confluence позволяет создать единую систему управления журналами изменений, повышающую прозрачность и эффективность. В этой статье мы поделимся опытом, как автоматизировать создание журнала изменений в Confluence с помощью сценария PowerShell, который извлекает информацию о выпуске из репозитория Azure DevOps.

Self-Hosted build Agent for Azure Pipelines
Self-Hosted build Agent for Azure Pipelines

К концу прочтения этой статьи у вас будет готовый скрипт, который автоматизирует извлечение информации журнала изменений из последней и предыдущей версий репозитория с помощью команд Git. Затем он использует модуль ConfluencePS для создания новой страницы Confluence, отображающей журнал изменений. Мы также настроим запуск сценария в Azure Pipelines при определенных условиях, например при создании нового тега в репозитории.

Давайте начнём!

Что нам необходимо?

  1. Получить информацию о выпуске.
  2. Получить журнал изменений между предыдущей и последней версией.
  3. Создать страницу в Confluence.
  4. Интегрировать наш скрипт с конвейеромAzure.

Начнем с подготовки Confluence к созданию новой папки журналов изменений.

Шаг 1. Создание родительской страницы:

  • Войдите в свою учетную запись Confluence.
  • Перейдите в пространство, в котором вы хотите создать папку журналов изменений.
  • Создайте новую страницу, которая будет служить родительской страницей для всех будущих страниц журналов изменений. Это можно сделать, выбрав «Создать» и следуя инструкциям по созданию страницы.

Шаг 2. Получение SpaceKey:

  • SpaceKey обычно отображается в URL-адресе, когда вы находитесь в пространстве Confluence.
  • Если ключ не отображается в URL-адресе, его можно найти, перейдя в Инструменты пространства > Обзор > Сведения о пространстве.

Шаг 3: Получение идентификатора родительской страницы:

  • Идентификатор родительской страницы (ParentID) можно найти в URL-адресе, когда вы находитесь на родительской странице. В URL-адресе страницы посмотрите параметр pageId, это и будет ParentID.

Шаг 4. Ввод URL-адреса сайта Confluence:

  • URL-адрес вашего сайта Confluence — это адрес, который вы используете для входа в Confluence. Например, https://yourcompany.atlassian.net/wiki.

[⚠️ Внимание:] Убедитесь, что у вас есть соответствующие разрешения для создания и редактирования страниц в выбранном вами пространстве Confluence.

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

Шаг 5: Создание скрипта PowerShell

Создайте файл с подходящим названием в корне вашего репозитория, у нас будет confluence.ps1

Сначала наш скрипт получает список изменений между этими версиями. (строки 1–11)

Затем скрипт создает новую страницу Confluence, на которой отображается журнал изменений, используя модуль ConfluencePS, и передает его в переменную среды для нашего конвейера. (строки 13–33).

Param ([String]$username, [String]$password) # Get username and password options from Azure Pipeline
$repoPath = "." # Set the repository path as the current directory
$currentVersion = git describe --abbrev=0 HEAD  # Get the latest version of the repository using git
# Write-Host $currentVersion
$prevVersion = git describe --abbrev=0 $currentVersion^  #Get the previous version of the repository using git
# Write-Host $prevVersion
$changelog = git log --no-merges --pretty="- %s<br />" "$prevVersion..$currentVersion"  #Get the list of changes between the two versions using git
# Write-Host $changelog
# exit -0
$confluenceUrl = "https://your.atlassian.net/wiki"  #Set the Confluence URL
$securePassword = $password | ConvertTo-SecureString -AsPlainText -Force #Convert the password to a secure string
$credentials = New-Object System.Management.Automation.PSCredential `
     -ArgumentList $username, $securePassword   #Create a credential object for Confluence
#Check if the module ConfluencePS is installed
if (-not (Get-Module -Name ConfluencePS -ListAvailable)) {
    Install-Module -Name ConfluencePS -Scope CurrentUser -Force
}
Import-Module ConfluencePS # Import the module ConfluencePS
Set-ConfluenceInfo -BaseURI $confluenceUrl -Credential $credentials   #Set the information about Confluence using the URL and credentials
$body = @"
<h2>What's new in comparison with version $prevVersion</h2>
<pre>$changelog</pre>
"@
$page = New-ConfluencePage -Title "What's new in $currentVersion" -SpaceKey YOURSPACEKEY -ParentID YOUR_PARENT_ID -Body $body  #Create a new Confluence page with the given title, space key and body
$pageObj = Get-ConfluencePage -PageID $page.ID     # Get the Confluence page object by ID
Write-Output $pageObj.URL     #Print the page URL to the screen
Write-Host "##vso[task.setvariable variable=confluenceUrl]$($pageObj.URL)"    #Set the variable confluenceUrl for Azure Pipeline using the page URL

[⚠️ Внимание:] Чтобы использовать этот скрипт, вам необходимо изменить следующее: $confluenceUrl на URL-адрес вашего сайта Confluence. (строка 13)
YOURSPACEKEY на ключ вашего пространства в Confluence. (строка 30)
YOUR_PARENT_ID в идентификаторе родительской страницы, на которой должна быть создана новая страница. (строка 30)

  • Убедитесь, что Git установлен и доступен в вашем пути к скрипту.
  • Убедитесь, что у вас есть права на создание страниц в указанном пространстве Confluence.
  • Если вы не используете Azure Pipeline, удалите или измените строки, связанные с Write-Host, «##vso[task.setvariablevariable=confluenceUrl]$($pageObj.URL)», чтобы они соответствовали вашей среде выполнения.

Вы также можете поэкспериментировать с телом страницы и списком данных, которые вы хотите отправить в журнал изменений.

Шаг 6. Интеграция с конвейерами Azure.

Задача предназначена для запуска в Azure Pipelines и запускается только при определенных условиях (condition), при создании нового тега в репозитории. Переменные $USERNAME и $PASSWORD хранятся в секретах конвейера и передаются во время запуска. Данная задача вызывает запуск нашего скрипта .\confluence.ps1.

Azure Pipeline Task

- task: PowerShell@2
  condition: and(not(eq(variables['Build.Reason'], 'PullRequest')), BeginsWith(variables['Build.SourceBranch'], 'refs/tags/'))
  displayName: Create a changelog and create a page in Confluence.
  inputs:
    file path: .\confluence.ps1
    arguments: '-username $(USERNAME) -password $(PASSWORD)'

Добавьте её в свой конвейер Azure. Поздравляю, у вас есть страница с журналом изменений!

Заключение

Автоматизация журналов изменений с помощью Azure DevOps и Confluence упрощает процесс документирования и поддерживает актуальность информации. Такой подход позволяет командам сосредоточиться на разработке, оставив рутинную работу по документированию изменений.

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

Желаем отличного настроения и интересных задач!