Build task

Using the Bravo Notes build task you can automate part of the release notes process.

How to use the Bravo Notes build task

Before you can use the Bravo Notes build task you have to create a Bravo Notes template first.

Once you have your first template ready you can select the template in your build task.

Using inside a build pipeline

Just add the Bravo Notes build task to a build pipeline. By default, all work items associated with a running build will be used to generate the output document

See below how to configure the build task.

Using inside a release pipeline

Just add the Bravo Notes build task to a release pipeline. By default, all work items associated with the primary source build artifact of a running release will be used to generate the output document. All work items that were associated with source builds since the previous successful release will be considered.

See below how to configure the build task.

Build task options

The following options are available to control the behavior of the build task.

Bravo Notes template
The source document to use. This includes the template for the main document, any PDF-specific templates, label settings and other settings that control how the document is generated.

Work item source
Determines what work items are used to generate the output document. Options are:

Source option	Description
Associated work items	See sections above on how associated work items are pulled in from a build or release pipeline.
Associated Work items since specified starting commit	Retrieve associated work items between the source commit of build artifacts and the specified commit hash
Compare with release environment	Retrieve associated work items that have not yet been released to the selected release environment
Compare with environment (YAML)	Retrieve associated work items that have not yet been released to the selected environment in a YAML pipeline
Query	Use the selected query as the source for work items. All types of queries are supported. Results of hierarchical queries will be turned into a flat list.
Iteration: Current	Retrieve all work items selected for the current iteration.
Iteration: Current - 1	Retrieve all work items selected for the previous iteration.
Iteration: Current + 1	Retrieve all work items selected for the next iteration.
JSON file	Specify the path to a JSON file including work item ids. The expected format is [ {"id": 12345}, {"id": 56789} ]

Work items to resolve

Determines how work items should be retrieved. Options are:

All directly associated Work items - all work items associated to a build / release or read from a file wil be used
Selected types - only work items of the specified work item types will be considered. Starting from the directly associated work items Bravo Notes will look for parent work items that match one of the selected types

Output format
Choose the format of the document to generate. Options are:

Markdown
HTML
PDF - note that PDFs are generated on our backend

Handle images
Determines how images referenced in work item HTML fields and stored in Azure DevOps are handled. Options are:

Keep as is - image sources will be left unaltered
Download to images folder - images will be downloaded to the folder "images" next to the generated target file
Publish and host on bravonotes.com - images will be uploaded to our backend and hosted on a publicly available Azure storage account behind bravonotes.com

Output target
Determines where to store the generated document. Options are:

File - store generated document in the specified path
Wiki - store generated document as a page in the specified Azure DevOps Wiki

Important: Make sure to give the build agent service Contribute permissions via the Wiki security settings.
Repository - select a repository and path to save the generated document to
Confluence - save your generated HTML document to a Confluence page

Output file path
The path to store the generated document when the output format is set to "File". Subdirectories contained in the path will be created automatically if necessary.

Target Wiki
The Wiki to store the generated document in.

Wiki page path
The path to the Wiki page to store the generated document in.

Wiki branch
When a Code Wiki is selected, specify a branch to push to.

Target repository
Git repository to store the generated file.

Target branch
Git repository branch to push to.

Commit message
Commit message to use for the commit when pushing to the selected Git repository.

Commit author email
Auhtor email to use for the commit when pushing to the selected Git repository.

Handle empty work item list
Specify how the build task should behave when no work items could be retrieved from the build task.

Add attachment to pipeline result
Uses the markdown representation of the template rendering and publishes it to Azure Pipelines so it can be permanently seen in the pipeline summary page

Attachment title
Specify the title to be used when adding an attachment to pipeline result

Using build variables in your template

Built-in and custom non-secret build variable can be output in your template using this syntax

## Build / release pipeline variables (secret variables won't be accessible)

{{ env 'YOUR_BUILDVARIABLE' }}

## Build variables

{{ env 'BUILD_BUILDNUMBER' }}
{{ env 'BUILD_SOURCEBRANCH' }}

## Release (classic) variables

{{ env 'RELEASE_ENVIRONMENTNAME' }}
{{ env 'RELEASE_RELEASEDESCRIPTION' }}

Make sure to replace dots with underscores and make everything uppercase.

Release.ReleaseDescription => RELEASE_RELEASEDESCRIPTION

Find a list of all available pre-defined variables for:

Also there are a few shortcuts to output common build and release values

Build-ID: {{ build.id }} 
Build number: {{ build.name }}
Build pipeline name: {{ build.definition.name }}

Release-ID {{ release.id }}
Release name {{ release.name }}

Need access to more data in your templates? Feel free to reach out. We might be working on it.

Common issues

Should your build task fail the information below might help.

When publishing to a Wiki the task fails with a permission error

To allow the Bravo Notes build task to publish to your Azure DevOps Wiki you need to give Contribute permissions to the account Project Collection Build Service

If you have the Limit job authorization scope to current project for (non-) release pipelines option enabled in Project Settings > Pipelines > Settings you need to give Contribute permissions to the [Your Project Name] Build Service.

If you have the Limit job authorization scope to referenced Azure DevOps repositories option enabled in Project Settings > Pipelines > Settings you won't be able to publish to a Wiki unless you are using a YAML pipeline and explicitly reference the Wikis repository (learn more).