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

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:

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

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:

• Build pipelines
• Release pipelines (classic)

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).