Are YAML build pipelines updateable with Update-VSTeamBuildDefinition?

[klabranche]

I have a yaml based build in my repository. We want to change the name of the build pipeline using Update-VSTeamBuildDefinition.

Steps to reproduce

    $buildDefMeta = Get-VSTeamBuildDefinition -ProjectName TeamProject -Filter "myApp CI" -Type build

    $buildDef = Get-VSTeamBuildDefinition -ProjectName TeamProject -id $buildDefMeta.ID -Raw

    $buildDef.name = $buildDef.name.replace(" ","-")

    $buildJson = $buildDef | ConvertTo-Json -Depth 100

    #update expects json file of build def.... just want to rename the build without a space...
    Update-VSTeamBuildDefinition -ProjectName TeamProject -Id $buildDefMeta.ID -BuildDefinition $buildJson

As an extra test, I saved the $buildJson result as a file and tried to import a build pipeline and got a different error. I'm thinking yaml based CI builds at this point aren't really supported for automation like this...???

Expected behavior

The build definition name would change from `myApp CI` to `myApp-CI`

Actual behavior

Error: 

WARNING: The trigger settings source 2 is not valid with process type 1.
Invoke-RestMethod : {"$id":"1","innerException":null,"message":"The trigger settings source 2 is not valid with process type 
1.","typeName":"Microsoft.TeamFoundation.Build.WebApi.InvalidDefinitionException, 
Microsoft.TeamFoundation.Build2.WebApi","typeKey":"InvalidDefinitionException","errorCode":0,"eventId":3000}
At MyLocalPath\WindowsPowerShell\Modules\VSTeam\6.4.8\vsteam.functions.ps1:268 char:18

Environment data

OS

• [ ] macOS
• [X ] Windows
• [ ] Linux

Server

• [ ] TFS 2017
• [ ] TFS 2018
• [ X] Azure DevOps Server (Version Dev17.M153.5)
• [ ] Azure DevOps Service

> Get-VSTeamAPIVersion

Name                           Value                                                                                                                                                    
----                           -----                                                                                                                                                    
Release                        3.0-preview                                                                                                                                              
Version                        TFS2017                                                                                                                                                  
MemberEntitlementManagement                                                                                                                                                             
TaskGroups                     3.2-preview.1                                                                                                                                            
DistributedTask                3.0-preview                                                                                                                                              
Core                           3.0                                                                                                                                                      
Packaging                                                                                                                                                                               
ServiceFabricEndpoint                                                                                                                                                                   
VariableGroups                 3.2-preview.1                                                                                                                                            
Build                          3.0                                                                                                                                                      
Git                            3.0                                                                                                                                                      
ExtensionsManagement           3.0-preview                                                                                                                                              
Graph                                                                                                                                                                                   
Policy                                                                                                                                                                                  
Tfvc                           3.0                                                                                                                                                      

>$PSVersionTable

Name                           Value                                                                                                                                                    
----                           -----                                                                                                                                                    
PSVersion                      5.1.19041.1                                                                                                                                              
PSEdition                      Desktop                                                                                                                                                  
PSCompatibleVersions           {1.0, 2.0, 3.0, 4.0...}                                                                                                                                  
BuildVersion                   10.0.19041.1                                                                                                                                             
CLRVersion                     4.0.30319.42000                                                                                                                                          
WSManStackVersion              3.0                                                                                                                                                      
PSRemotingProtocolVersion      2.3                                                                                                                                                      
SerializationVersion           1.1.0.1         

[klabranche]

Further Research:

I was able to use the Get Build Definition API and Put directly to update the YAML builds Name.

I used Postman to get the build definition for a YAML based build Pipeline and compared it to what Get-VSTeamBuildDefinition -ProjectName TeamProject -id $buildDefMeta.ID -Raw returns and found that Get-VSTeamBuildDefinition is missing the process section:

"process": {
        "yamlFilename": "/azure-pipelines.yml",
        "type": 2
    },

I can only assume that the absence of this means it defaults to a process type of 1 and we get the error.

[SebastianSchuetze]

Thanks for the research. Do you think you feel comfortable enough to make a PR and try to fix it? Otherwise, I can try but I can't promise when.

[klabranche]

I would love to if I can find some time... :-) Thanks for the quick response!

[klabranche]

So I've been spelunking the code to understand it. I've come across something I'm not sure I fully understand... The VSTeamVersions class have versions for the areas of api calls. It also have a version that if not set defaults to TFS2017. I see where I am to set this if I am running integration tests but not elsewhere. So It appears to me that when I call Get-VSTeamBuildDefinition it ends up calling the 3.0 api. I've confirmed this in Fiddler. I have personally set TEAM_VERSION env var to TFS2018 and AzD2019 to which they don't affect it.

The underlying _callAPI is passing -Version and it's based off of _getApiVersion Area (Build). That is set to 3.0 and it doesn't seem like I can override that anywhere as matter of just being a user of the API. The 3.0 api is way before yaml builds and thus the process part of the build json is never returned since 3.0 api doesn't know about it....

I also see that the _getApiVersion call has an additional optional parameter for Target which if present uses the set TEAM_VERSION env variable. Again, that doesn't look like something I can override/pass in as just a user of Get-VSTeamBuildDefinition.

Am I understanding all this right?

I'm feeling a bit cautious at the moment that I've not set something properly as just a user of the API but perhaps it is a bug that a consumer of the modules can't change the api version and it's stuck at 3.0 in the areas?

FYI - my earlier comments on Postman working, I was passing the api version of 5.0 or 5.0-preview....

[SebastianSchuetze]

Thanks for the research. Even if it is confusing for you, I think you are on the right track. Have you tried setting the version manually with the cmdlet Set-VSTeamAPIVersion? Is not this is the place where you can set the version. Usually, I would expect that the correct version is set when you configure the account with the PAT.

https://github.com/MethodsAndPractices/vsteam/blob/master/.docs/Set-VSTeamAPIVersion.md

[klabranche]

So I Set-VSTEAMAPIVersion to AzD2019 and the calls appear to ignore it which is what I thought I was seeing in the private function calls.... It calls the 3.0 api. I confirmed again with Fiddler.

As an aside, are we supposed to set the version? I am on prem so I used -UseWindowsAuthentication in the Set-VSTeamAccount.

I did also use a PAT and got the same result. 3.0 api is called.

[SebastianSchuetze]

Interesting. Let me at least add @DarqueWarrior if he has a clue out of the blue. Of not I gonna research this as well.

[klabranche]

Ugh... So, I believe I found two issues. One that was MY BOX and one that is documentation lacking maybe?

My box had several versions of VSTeam including a really old one. It seems that I was running the older one which I didn't expect but once I uninstalled it I was able to get things working.

Sooooooo soooooo sorry. Now, with that out of the way:

I still had to Set-VSTEAMApiVersion which I wasn't really seeing anywhere in documentation to be sure to do. I might have missed it, but I didn't see it....?

So to this end, this issue is a non-issue in that the Get-VSTeamBuildDefintion and Update-VSTeamBuildDefinition support yaml builds and changes as long as Set-VSTeamApiVersion is properly set....

Perhaps after all this is just a documentation issue.

[SebastianSchuetze]

Thanks for all the research. The documentation exists at https://github.com/MethodsAndPractices/vsteam/blob/master/docs/Set-VSTeamAPIVersion.md.

But maybe the default API version for Azure DevOps Server 2019 should be updated for the default. I am not sure if that is already done and not working properly or if it is really outdated.

[klabranche]

I more mean, as I learned about this module and worked to use it as a consumer I didn't have anything that said First set your team account via Set-VSTeamAccount and then set your API level via Set-VSTeamApiVersion THEN call all other APIs. The first actually happens by getting a helpful error message when making a call to any API and you haven't set Team Account yet. This includes Set-VSTeamApiVersion.md. It tells me what it does BUT it doesn't tell me I better set this before calling other API calls OR you will get the default level which currently is X.

Does that make sense?

Addendum.... welp again on my part...

I see if I do get-help about_vsteam I see what I essentially was asking for.... I must admit I almost always use the repo mds to understand this stuff...

About the only thing I would recommend and would be happy to do if agreed to:

Add the long description essentially found in get-help about_vsteam to the readme.md as a new section after installation, called Basic usage.

[SebastianSchuetze]

ok, then I gonna close this issue and consider your suggestions!

[klabranche]

I can update the main readme.md for this and thinking of having a reusable section for all the help called Prerequisites and add it to the NOTES section. In it we can specify to the set team as a must and then consider set default project, set api version and set api timeout in this section.

Good/bad/thoughts?

[klabranche]

Something like:

[SebastianSchuetze]

Yes please make a PR for the docs. Good idea. About the extend or how much we will see when you wrote it. Anything that makes it clearer is good.

And for the notes. Check also to build the module and if it is rendered correctly for the PS module help (Get-Help) cmdlet. These docs are not just markdown but also the basis for the integrated PS help.

[klabranche]

It does render correctly only after removing the markdown links from what I can tell but only when calling get-help add-vsteam -full for example. Notes are only displayed with the -full parameter....

Is there a way to keep the links in there for the non ps (Get-Help) route. Like Related Links in the Get-Help route don't show the markdown link....?

Update:

I spelunked the platyPS code and looks like this is a no.... I'll just remove the markdown links in the Notes.

[klabranche]

I cleaned up notes to play nice in get-help.

I also added to the related functions the four calls one would want to consider. I did this since notes only show when one calls get-help with the -full parameter and the fact that the links break in notes when converted for get-help. I want anyone running get-help without full to see those functions as a way to draw attention to these calls as truly related. I would hope then that someone might actually go look at the help on those and realize I better set these for example.....

Let me know if you like that or not. Thanks!

Mock ups for your review:

Get-Help example:

Markdown result file example:

[SebastianSchuetze]

Looks good and no need to wait for a PR until it's perfect. You can just PR this and we take the discussion from there. Collaboration on PRs is much easier than with screenshots. ☺️