How to generate a document from an Azure DevOps Pipeline?

This week, while meeting with my partner and good friend Rik Hepworth, he posed an interesting question: “Mike, we really appreciate Azure Documenter in Turbo360, but wouldn’t it be fantastic if we could generate documentation automatically from a DevOps pipeline? That way, every time we deploy updates to Azure, the documentation could be regenerated.”

In this article, we will explore how to achieve this.

Creating Your Document

To start off, I have created a document that can be generated with the appropriate settings. Here, I am using the Azure Resource Details document type, as illustrated below.

As a helpful tip, you can use any document type for this method. However, within Azure Documenter, there’s a feature that enables you to schedule document generation. This covers many use cases, especially for generating resource details directly from a pipeline.

When setting up your document, you can apply filters to specify which resources to include. For instance, you might want to focus on particular resource groups or tags, as displayed below.

Obtaining Your API Key

The next step involves creating an API key, which can be done in the settings section of Turbo360. This key is necessary for accessing Azure Documenter.

Script for Document Generation

To generate the document from your pipeline, you’ll need to interact with the Turbo360 API. There are two essential operations to perform:

• GetDocumentConfigurations
• GenerateDocument

Using GetDocumentConfigurations, you can retrieve the ID and document type based on the document’s name that you wish to trigger. The next step is to invoke the GenerateDocument operation with those details.

The following PowerShell script demonstrates how to do this:

    $documentName = "Your document name here"
$apiKey = ""
$baseUrl = "https://portal.turbo360.com/AzureDocumenter/"

# Optional: Define headers
$headers = @{
  "APIKey" = $apiKey
  "Content-Type" = "application/json"
}

# Fetch Document Configurations
$url = $baseUrl + "GetDocumentConfigurations"
$documentConfigurationResponse = Invoke-RestMethod -Uri $url -Method GET -Headers $headers
Write-Host $documentConfigurationResponse

$id = ""
$documentType = ""

# Iterate through configurations
foreach ($item in $documentConfigurationResponse) {
  if ($item.name -eq $documentName) {
    $id = $item.id
    $documentType = $item.documentType
    Write-Host "Found matching object:"
    Write-Host "ID: $id"
    Write-Host "Document Type: $documentType"
    break
  }
}

# Trigger Document Generation
$url = $baseUrl + "GenerateDocument"
$body = @{
  "id" = $id
  "documentType" = $documentType
} | ConvertTo-Json

$documentGenerateResponse = Invoke-RestMethod -Uri $url -Method POST -Headers $headers -Body $body
Write-Host $documentGenerateResponse
    
  

Integrating with Azure DevOps Pipeline

The next step is to use this PowerShell script in your Azure DevOps Pipeline. Ideally, you should store the API key as a variable or retrieve it from Azure Key Vault for added security.

In your pipeline, you can add a PowerShell task using the script above, slightly adjusted to obtain the API key from a variable. See the example below:

This pipeline setup is straightforward and simply triggers the document generation. While your overall pipeline may handle more complex tasks, consider appending this PowerShell task at the conclusion of your pipeline activities.

Below is an example screenshot showing the successful execution of the pipeline, triggering the document generation.

Once the process is complete, you can download the updated document from Turbo360, ensuring your Resource Details are up to date.

We hope this guide provides you with valuable insights on integrating documentation features with your DevOps practices, fostering robust governance for your solutions.

Further Reading