During the last major release of my commanding framework I wrote a lot of new documentation. I wrote this in Markdown and converted it to a documentation website using DocFX resulting in this website.
DocFX has a VSTS extension which make it easy to integrate into your build and release pipeline but I couldn’t find any simple way to publish it to GitHub Pages which is what I am using as a simple, and free, host. My initial solution was to use a short PowerShell script which took the following steps as part of a Release Plan:
- Clone the gh-pages branch from my repository into a folder
- Copy the output from the DocFX build artefact to the folder
- Commit the changes
- Push the branch to GitHub (which publishes the changes)
This worked nicely but it irked me not being able to do it in a more off the shelf manner and so I’ve tidied this up and released a VSTS Build and Release task to the marketplace. It come complete with documentation and hopefully it’s useful to people. The source code is available on GitHub.
Writing a simple VSTS build and release task is well documented and there are plenty of blog posts on the topic and so I won’t repeat that here but I did think it might be helpful to quickly cover just a couple of things that were often not covered.
Accessing Variables
I needed to find the default working folder within my task as I needed scratch space for cloning the gh-pages branch. VSTS exposes this as a built-in variable called System.DefaultWorkingDirectory – it’s a commonly used variable and you’ve probably seen it expressed as $(System.DefaultWorkingDirectory) when using tasks for releases.
You can access variables from within a script by using the Get-VstsTaskVariable cmdlet. For example:
$defaultWorkingDirectory = Get-VstsTaskVariable -Name 'System.DefaultWorkingDirectory'
Reporting Errors
You can write to the VSTS log using the Write-Host cmdlet but I wanted a nice red error message when things went wrong. You can do this by prefixing your message as shown below:
Write-Host "##vso[task.logissue type=error;]Your error message"
To exit the script and have it fail you need to exit with a non-zero return code and using a specific Exit method:
[Environment]::Exit(1)
And that’s it. As always I hope this is useful and I can be reached for discussion and questions on Twitter.