Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Update the documentation over agent scope #898

Merged
merged 2 commits into from
Dec 7, 2020
Merged

Update the documentation over agent scope #898

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4615d79
Update the documention over agent scope
rfennell Dec 7, 2020
8654d19
ETIMEDOUT Documentation
rfennell Dec 7, 2020
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 37 additions & 7 deletions Extensions/XplatGenerateReleaseNotes/readme.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,7 +19,7 @@ Generates release notes for a Classic Build or Release, or a YML based build. Th
> **IMPORTANT** - There have been three major versions of this extension, this is because
> * V1 which used the preview APIs and is required if using TFS 2018 as this only has older APIs. This version is not longer shipped in the extension, but can be download from [GitHub](https://github.com/rfennell/AzurePipelines/releases/tag/XPlat-2.6.9)
> * V2 was a complete rewrite by [@gregpakes](https://github.com/gregpakes) using the Node Azure DevOps SDK, with minor but breaking changes in the template format and that oAuth needs enabling on the agent running the tasks. At 2.27.x [KennethScott](https://github.com/KennethScott) added support for [Handlbars](https://handlebarsjs.com/) templates.
> * V3 removed support for the legacy template model, only handlebars templates supported.
> * V3 removed support for the legacy template model, only handlebars templates supported as this is a far more flexible solution and allow much easier enhancement of this task

# Overview
This task generates a release notes file based on a template passed into the tool. It can be using inside a [classic Build, a classic Release](https://docs.microsoft.com/en-us/azure/devops/pipelines/get-started/pipelines-get-started?view=azure-devops#define-pipelines-using-the-classic-interface) or a [Multistage YAML Pipeline](https://docs.microsoft.com/en-us/azure/devops/pipelines/get-started/pipelines-get-started?view=azure-devops#define-pipelines-using-yaml-syntax).
Expand All @@ -33,7 +33,7 @@ The data source for the generated Release Notes is the Azure DevOps REST API's c
There are many ways that the task can be used. A common pattern is to use the task multiple times in a pipeline

1. Run once for every build, so you get the build notes of what is in that build
1. Run as part of a deployment stage, checking against the last successful build, to generate the release notes issued with that release.
1. Run as part of a deployment stage, checking against the last successful deployment to that stage, to generate the release notes specific to that release.

Possible sets of parameters depending on your usage are summarized below

Expand All @@ -53,7 +53,7 @@ There are [sample templates](https://github.com/rfennell/vNextBuild/tree/master/

<hr/>

**The legacy templating format has been be deprecated in V3. The only templating model supported is Handlebars**
**Note** The legacy templating format has been be deprecated in V3. The only templating model supported is Handlebars
<hr/>

## Handlebar Templates
Expand Down Expand Up @@ -138,9 +138,9 @@ Since 2.27.x it has been possible to create your templates using [Handlebars](ht

```

> **IMPORTANT** Handlebars based templates have different objects available to the legacy template used in V2 of this extension. This is a break change.
> **IMPORTANT** Handlebars based templates have different objects available to the legacy template used in V2 of this extension. This is a break change, so what out if migrating

> **IMPORTANT** You can find more sample templates [here](https://github.com/rfennell/AzurePipelines/tree/main/SampleTemplates/XplatGenerateReleaseNotes%20(Node%20based)/Version%203)
> **IMPORTANT** You can find more sample templates and extensions [here](https://github.com/rfennell/AzurePipelines/tree/main/SampleTemplates/XplatGenerateReleaseNotes%20(Node%20based)/Version%203)


What is done behind the scenes is that each `{{properties}}` block in the template is expanded by Handlebars. The property objects available to get data from at runtime are:
Expand All @@ -151,7 +151,7 @@ What is done behind the scenes is that each `{{properties}}` block in the templa
* **pullRequests** - the array of PRs (inc. labels, associated WI links and commits to the source branch) referenced by the commits in the release
* **inDirectlyAssociatedPullRequests** - the array of PRs (inc. labels, associated WI links and commits to the source branch) referenced by associated commits of the directly linked PRs. [#866](https://github.com/rfennell/AzurePipelines/issues/866)
* **tests** - the array of unique tests associated with any of the builds linked to the release or the release itself
* **builds** - the array of the build artifacts that CS and WI are associated with. Note that this is a object with three properties
* **builds** - the array of the build artifacts that CS and WI are associated with. The associated WI, CS etc. in ths object are also will the main objects above, this is a filtered lits by build. Note that this is a object with three properties.
- **build** - the build details
- **commits** - the commits associated with this build
- **workitems** - the work items associated with the build
Expand Down Expand Up @@ -331,4 +331,34 @@ However, within a release there are no such artifacts location. Hence, it is rec
# Local Testing of the Task & Templates
To speed the development of templates, with version 2.50.x, a [tool](https://github.com/rfennell/AzurePipelines/tree/master/Extensions/XplatGenerateReleaseNotes/V3/testconsole/readme.md) is provided in this repo to allow local testing.

Also there are now parameters (see above) to dump all the REST API payload data to the console or a file to make discovery of the data available in a template easier.
Also there are now parameters (see above) to dump all the REST API payload data to the console or a file to make discovery of the data available in a template easier.

# Troubleshooting

## Timeouts
This task makes many calls to the Azure DevOps REST API, the volume depends on the number of associated items with a build. This volume of calls can result in timeouts, it is assumed this is due to throttling by the API. If a timeout occurs the task fails with an error in the form

```
Error: connect ETIMEDOUT 13.107.42.18:443
```

At present, even though the task utilizes retry logic, there is no way to recover from these timeouts. The only solution is to retry the failed job, this will usually work (eventually)

## OAUTH Scope limiting what Associated Items can be seen
This task uses the build agent's access OAUTH token to access the Azure DevOps API. The permissions this identity has is dependant upon the [the Job authorization scope](https://docs.microsoft.com/en-us/azure/devops/pipelines/process/access-tokens?view=azure-devops&tabs=yaml#job-authorization-scope).

Cross project permissions are made more complex by the new default settings for recently created Team Projects (created since late 2020). These can effect this task's operation why trying to find associated items from other Team Projects.

> **Note** This setting is not a problem in older Team Projects, where the default setting to off

So, if you find that the `workItems` and `relatedWorkItems` objects are unexpectedly empty arrays when you expect values from other Team Projects check that the project settings:

`Project Settings > Pipelines > Limit job authorization scope to current project for release pipelines`

and

`Project Settings > Pipelines > Limit job authorization scope to current project for non-release pipelines`

they should both be set to `disabled`

> **Note** If you wish to confirm this is an issue you can inject a different PAT using the `overridePat` parameter. This PAT will be used in place of the OAUTH Token