I have posted in the past a quick script to generate some markdown documentation for the YAML usage of Azure DevOps Pipeline extensions. Well I decided that having this script as a task itself would be a good idea, so a wrote it, and please to say have just release it to the marketplace
The YAML Documenter task scans an extension’s vss-extension.json and task.json files to find the details it needs to build the markdown documentation on the YAML usage. It can also, optionally, copy the extension’s readme.md as the extensions primary documentation.
I am starting to use this extension, with my WIKIUpdater extension, in my release pipelines to make sure my extension’s GitHub WIki is up to date.
It is going to take a bit of work to update all my pipelines, but the eventual plan is to use the YAML document generator in the builds, adding the readme and YAML markdown files to the build as artefacts. Then deploying these files to the wiki in a later stage of the pipeline.
Hope some of you find it of use.
I am automating the process by which we keep our build agent up to date. The basic process is to use a fork of the standard Microsoft Azure DevOps Pipeline agent that has the additional code included we need, notably Biztalk.
Once I have the Packer created VM up and running, I need to install the agent. This is well document, just run .\config.cmd –help for details. However, there is no option to add user capabilities to the agent.
I know I could set them via environment variables, but I don’t want the same user capabilities on each agent on a VM (we use multiple agents on a single VM).
There was no documented Azure DevOps API I could find to add capabilities, but a bit of hacking around with Chrome Dev tools and Postman got me a solution, which I have provided a GIST
A major problem when moving from the graphic editing of Azure Pipeline builds to YAML has been the difficulty in knowing the options available, and of course making typos.
Microsoft have just released a VSCode extension to help address this problem – it is called Azure Pipelines
I have yet to give it a really good workout, but first impressions are good.
It does not remove the need for good documentation of task options, there is a need for my script to generate YAML documentation from a task.json file, but anything extra to ease editing helps.
I have just release a new Azure DevOps Pipelines extension to update a page in a Git based WIKI.
It has been tested again
- Azure DevOps WIKI – running as the build agent (so the same Team Project)
- Azure DevOps WIKI – using provided credentials (so any Team Project)
- GitHub – using provided credentials
It takes a string (markdown) input and writes it to a new page, or updates it if it already exists. It is designed to be used with my Generate Release Notes Extension, but you will no doubt find other uses
Whilst listening to a recent Radio TFS it was mentioned that TFS Aggregator uses the C# SOAP based Azure DevOps APIs; hence needed a major re-write as these APIs are being deprecated.
Did you know that there was a REST API alternative to TFS Aggregator?
My Azure DevOps Services & Server Alerts DSL is out there, and has been for a while, but I don’t think used by many people. It aims to do the same as TFS Aggregator, but is based around Python scripting.
However, I do have to say it is more limited in flexibility as it has only been developed for my (and a few of my clients needs), but its an alternative that is based on the REST APIs.
Scripts are of the following form, this one changes the state of a work item if all it children are done
# Expect 2 args the event type and a value unique ID for the wi
if sys.argv == "workitem.updated" :
wi = GetWorkItem(int(sys.argv))
parentwi = GetParentWorkItem(wi)
if parentwi == None:
LogInfoMessage("Work item '" + str(wi.id) + "' has no parent")
LogInfoMessage("Work item '" + str(wi.id) + "' has parent '" + str(parentwi.id) + "'")
results = [c for c in GetChildWorkItems(parentwi) if c["fields"]["System.State"] != "Done"]
if len(results) == 0 :
LogInfoMessage("All child work items are 'Done'")
parentwi["fields"]["System.State"] = "Done"
msg = "Work item '" + str(parentwi.id) + "' has been set as 'Done' as all its child work items are done"
SendEmail("firstname.lastname@example.org","Work item '" + str(parentwi.id) + "' has been updated", msg)
LogInfoMessage("Not all child work items are 'Done'")
LogErrorMessage("Was not expecting to get here")
I have recently done a fairly major update to the project. The key changes are:
- Rename of project, repo, and namespaces to reflect Azure DevOps (the namespace change is a breaking change for existing users)
- The scripts that are run can now be
- A fixed file name for the web instance running the service
- Based on the event type sent to the service
- Use the subscription ID, thus allowing many scripts (new)
- A single instance of the web site running the events processor can now handle calls from many Azure DevOps instances.
- Improved installation process on Azure (well at least tried to make the documentation clearer and sort out a couple of MSDeploy issues)
Full details are on the project can be seen on the solutions WIKI, maybe you will find it of use. Let me know if the documentation is good enough
There is a general move in Azure DevOps Pipelines to using YAML, as opposed to the designer, to define your pipelines. This is particularly enforced when using them via the new GitHub Marketplace Azure Pipelines method where YAML appears to be the only option.
This has shown up a hole in my Pipeline Tasks documentation, I had nothing on YAML!
So I have added a YAML usage page for each set of tasks in each of my extensions e.g the file utilities tasks.
Now, as are most developers, I am lazy. I was not going to type all that information. So I wrote a script to generate the markdown from respective task.json files in the repo. Now this script will need some work for others to use as it relies on some special handling due to quirks of my directory structure, but I hope it will be of use to others.