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:

  • 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
  • Query - Uses a 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.
  • 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 output format is set to "File". Sub directories 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)<br><br>{{ $env.YOUR_BUILDVARIABLE }}<br><br>## Build variables<br>
{{ $env.BUILD_BUILDNUMBER }}
{{ $env.BUILD_SOURCEBRANCH }}<br><br>## 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 publishing from the Bravo Notes build task to a Azure DevOps Wiki you need to give the build agent service Contribute permissions.

Did this answer your question? Thanks for the feedback There was a problem submitting your feedback. Please try again later.

Still need help? Contact Us Contact Us