Skip to content

GenerateReleaseNotes Node based Cross Platform Task YAML

Jump to bottom Edit New page
rfennell edited this page Feb 13, 2025 · 57 revisions

Generate Release Notes (Crossplatform)

The 'Generate Release Notes (Crossplatform)' package contains the following tasks. The table show the possible variables that can be used in YAML Azure DevOps Pipeline configurations

XplatGenerateReleaseNotes V4

Generates a release notes file in a format of your choice from the build or release history

YAML snippet

# Generate Release Notes (Crossplatform)
# Description - Generates a release notes file in a format of your choice from the build or release history
- task: XplatGenerateReleaseNotes@4
  inputs: 
     # Required arguments
     outputfile: 
     templateLocation: File
     templatefile: 
     inlinetemplate: 
     dumpPayloadToConsole: false
     dumpPayloadToFile: false
     replaceFile: True
     appendToFile: True
     getParentsAndChildren: False
     getAllParents: False
     getIndirectPullRequests: False
     stopOnError: False
     considerPartiallySuccessfulReleases: False
     checkForManuallyLinkedWI: False
     wiqlFromTarget: WorkItems

Arguments

  • Argument: outputfile
    • Description: The name of the Markdown file to export e.g. $(Build.ArtifactStagingDirectory)/releasenotes.md if within a build workflow
    • Type: string
    • Required: true
    • Default (if defined):
  • Argument: templateLocation
    • Description: Select the template file source, file in source control or in line.
    • Type: pickList
    • Required: true
    • Default (if defined): File
  • Argument: templatefile
    • Description: The name of the Markdown template.
    • Type: filePath
    • Required: true
    • Default (if defined):
  • Argument: inlinetemplate
    • Description: The Markdown template.
    • Type: multiLine
    • Required: true
    • Default (if defined):
  • Argument: checkStage
    • Description: If true a comparison is made against the last build that was successful to the current stage, or overrideStageName if specified (Build Only, for this to work the stage name must be unique in the pipeline)
    • Type: boolean
    • Required: false
    • Default (if defined): false
  • Argument: replaceFile
    • Description: Replace the output file
    • Type: boolean
    • Required: true
    • Default (if defined): True
  • Argument: appendToFile
    • Description: Append to end of file in the output file if not replacing file
    • Type: boolean
    • Required: true
    • Default (if defined): True

Advanced

  • Argument: overrideStageName
    • Description: If set uses this stage name to find the last successful deployment, as opposed to the currently active stage
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: stopOnRedeploy
    • Description: Do not generate release notes of a re-deploy. If this is set, and a re-deploy occurs the task will succeeds with a warning
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: sortCS
    • Description: If true will Changeset/Commits by data, if false then it will leave them in the API default order
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: sortWi
    • Description: If true will sort work items by type, if false then it will leave the work items in default order
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: showOnlyPrimary
    • Description: If true only show WI/CS associated with primary release artifact
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: searchCrossProjectForPRs
    • Description: If true will try to match commits to Azure DevOps PR cross project within the organisation, if false only searches the Team Project
    • Type: boolean
    • Required: false
    • Default (if defined): False
  • Argument: gitHubPat
    • Description: To expand commit messages stored in a private GitHub repos a PAT needs to be provided, it is not required for repo stored in Azure DevOps or public GitHub repos
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: bitbucketUser
    • Description: To expand commit messages stored in a private Bitbucket repos a user and app secret need to be provided, it is not required for repo stored in Azure DevOps or public Bitbucket repos
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: bitbucketSecret
    • Description: To expand commit messages stored in a private Bitbucket repos a user and app secret need to be provided, it is not required for repo stored in Azure DevOps or public Bitbucket repos
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: dumpPayloadToConsole
    • Description: If true the data objects passed to the file generator is dumped to the log
    • Type: boolean
    • Required: true
    • Default (if defined): false
  • Argument: dumpPayloadToFile
    • Description: If true the data objects passed to the file generator is dumped to a JSON file
    • Type: boolean
    • Required: true
    • Default (if defined): false
  • Argument: dumpPayloadFileName
    • Description: The filename to dump the data objects passed to the file generator
    • Type: string
    • Required: false
    • Default (if defined): $(Build.ArtifactStagingDirectory)/payload.json
  • Argument: getParentsAndChildren
    • Description: Find the parents and child workitems for any workitems associated with a build
    • Type: boolean
    • Required: true
    • Default (if defined): False
  • Argument: getAllParents
    • Description: Find the parents all workitems associated with a build, recursing back to workitem with no parents e.g. up to Epics
    • Type: boolean
    • Required: true
    • Default (if defined): False
  • Argument: tags
    • Description: A comma separated list of pipeline tags that must all be matched when looking for previous successful builds, only used if checkStage=true
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: overridePat
    • Description: It is possible to inject a Personal Access Token to use in place of the Build Agent OAUTH token. This option will only be used in very rare situations usually after a support issue has been raised
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: overrideActiveBuildReleaseId
    • Description: For releases or multi-stage YAML this parameter provides a means to set the ID of the 'active running release' to compare against. If the specified release/build is not found then the task will exit with an error. Default is empty/not set disabling this override behaviour
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: overrideBuildReleaseId
    • Description: For releases or multi-stage YAML this parameter provides a means to set the ID of the 'last good release' to compare against. If the specified release/build is not found then the task will exit with an error. Default is empty/not set disabling this override behaviour
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: getIndirectPullRequests
    • Description: If enabled an attempt will be made to populate a list of indirectly associated PRs i.e PR that are associated with a PR's associated commits
    • Type: boolean
    • Required: true
    • Default (if defined): False
  • Argument: maxRetries
    • Description: The number of time to retry any REST API calls that timeout. Set to zero for no retries, defaults to 20
    • Type: string
    • Required: false
    • Default (if defined): 20
  • Argument: pauseTime
    • Description: No longer used, but left in to avoid breaking YAML builds
    • Type: string
    • Required: false
    • Default (if defined): 5000
  • Argument: stopOnError
    • Description: If enabled will stop the pipeline if there is a Handlebars template error, if false the task will log the error but continue
    • Type: boolean
    • Required: true
    • Default (if defined): False
  • Argument: considerPartiallySuccessfulReleases
    • Description: If enabled both successful and partial successful release will be considered when looking for historic releases
    • Type: boolean
    • Required: true
    • Default (if defined): False
  • Argument: checkForManuallyLinkedWI
    • Description: By default WI associated manually with a build/release will not appear in release notes. If this parameter is true they will be added.
    • Type: boolean
    • Required: true
    • Default (if defined): False
  • Argument: wiqlWhereClause
    • Description: A where clause to get a get a list of work items using a WIQL Query e.g. [System.TeamProject] = 'Project Name' and [System.WorkItemType] = 'Product Backlog Item'. Note you cannot use the all the @ parameter such as @project, @currentIteration or @Me, but @Today works.
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: wiqlFromTarget
    • Description: The FROM target for the WIQL Query. e.g. SELECT [System.Id] FROM workitems WHERE ...
    • Type: pickList
    • Required: true
    • Default (if defined): WorkItems
  • Argument: wiqlSharedQueryName
    • Description: The name (can include sub folder path) of a Shared Work Item Query in the Shared Queries folder that will be used to retrieve work items e.g. Query1 or MyFolder/Query1. Notes: This parameter if defined will be used in preference to the other WIQL parameters. The query must be saved as 'shared query'. As with the other WIQL parameters, you cannot use the all the @ parameter such as @project, @currentIteration or @Me, but @Today works, and the query must return the Work Item ID as a column
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: getPRDetails
    • Description: If true all PRs in the project, or organisation, will be scanned for associations. There is an option to disable this feature as this scan is slow and not always required (Default true)
    • Type: boolean
    • Required: false
    • Default (if defined): true
  • Argument: getPRDetailsRepositoryId
    • Description: Helps improving performance during Get PR details step by filtering only the PRs of specific Azure DevOps Git repo (Default to not set i.e. search all repos)
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: getPRDetailsRefName
    • Description: Helps improving performance during Get PR details step by filtering only the PRs merged into specified branch e.g. refs/heads/main (Default to not set i.e. search all branches)
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: matchPRsByMergeCommit
    • Description: If true, matches PRs using only Merge Commit IDs, if false matches PRs using any Commit IDs (Default true)
    • Type: boolean
    • Required: false
    • Default (if defined): true
  • Argument: getTestedBy
    • Description: If true any Test Case WIs linked to associated WIs by a 'Tested By' relation will be added to the 'testedByWorkItems' array (Default true)
    • Type: boolean
    • Required: false
    • Default (if defined): true

Handlebars

  • Argument: customHandlebarsExtensionCodeAsFile
    • Description: A file with custom Handlebars extension written as a JavaScript module e.g. module.exports = {foo() {return 'Returns foo';}};
    • Type: string
    • Required: false
    • Default (if defined):
  • Argument: customHandlebarsExtensionCode
    • Description: A custom Handlebars extension written as a JavaScript module e.g. module.exports = {foo() {return 'Returns foo';}};
    • Type: multiLine
    • Required: false
    • Default (if defined):
  • Argument: customHandlebarsExtensionFile
    • Description: The filename (without extension) for any custom Handlebars extension written
    • Type: string
    • Required: false
    • Default (if defined): customHandlebarsExtension
  • Argument: customHandlebarsExtensionFolder
    • Description: The folder to save custom Handlebars extension file. If empty defaults to customHandlebarsExtensionFolder the agents temp folder '${process.env.AGENT_WORKFOLDER}/_temp'
    • Type: string
    • Required: false
    • Default (if defined):

Outputs

  • Argument: outputVariableName
    • Description: The name of the variable that the markdown output should be assigned to for use later in your workflow.
    • Type: string
    • Required: false
    • Default (if defined):

Extension 1 vss-extension.json (Edited for new paths) readme.md license.md images (for extension) logo.png screenshot1.png Task 1 (PowerShell based new layout) src icon.png task.json mytask.ps1 tasklibrary.psm1 (optional as needed) test mytask.tests.ps1

Add a custom sidebar
Clone this wiki locally