Azure Repos: git branching with a provisioned wiki
Azure DevOps supplies two types of wikis: published and provisioned. The former is a transparent part of Azure Repos and adheres to a regular git approach. The provisioned wiki, however, is a bit of an odd duck. It does allow you to use git branching but the documentation on that is scarce, and the user interface is not very clear. So, my team set off on a little quest for clarity.
Our challenge
Can we develop a provisioned wiki much like we develop our code with a branching strategy (GitHub Flow) and related Repository and Branch Policies in place?
The rationale
We are using a published wiki for developer documentation, keeping our docs as close to the code as possible. Plus, we are using the provisioned wiki for user documentation, keeping it as far away from the code as possible 🙃
In addition, we have a number of Repository and Branch Policies in place, safeguarding our development efforts. Apparently these policies also apply to the provisioned wiki. For example: Having a policy on the default branch with “Check for comment resolution” set to Required prohibits unencumbered pushing not only to repositories, but also to the default branch (wikiMaster) of a provisioned wiki. Which is exactly what we want.
Now, how do we go about our regular git branching strategy? Creating pull requests for a provisioned wiki and reviewing them before merging with the main branch?
Our approach
The Azure DevOps browser user interface (BUI) does not offer a very smooth user experience for developing a provisioned wiki, and there is also not much info to be found on it. However, the whole .wiki repository pretty much works like any other repository - albeit with a little quirk.
After cloning a provisioned repository via git clone git@ssh.dev.azure.com:v3/{organization}/{project}{project}.wiki we end up with a local repository called {project}.wiki and a default branch called wikiMaster. After which we cangit branch {feature_branch} and git add . && git commit -m “update user documentation” && git push --set-upstream origin {feature_branch} on it and head over to our browser.
However the .wiki repo is nowhere to be found or selected in the Azure Repos menu. Menu items like Branches and Pull requests for the provisioned wiki can only be reached by editing the URL from …/_git/<repo>/pullrequests… to …/_git/<repo.wiki>/pullrequests…
Once we’ve edited the URL we can use the Azure Repos menu as usual, to some extent. The menu will redirect us to a regular repo URL if we’re not watching 😉
As a basic solution we bookmarked the provisioned wiki URL in our browsers:
https://dev.azure.com/{organization}/{project}/_git/{project}.wiki/pullrequests
Some of us use the CLI to get to the right URL by using the--open flag.az repos pr create --openwill create a pull request and open it in a browser. Furthermore, az repos pr list --output table will show you the pull requests and az repos pr show --id {id} --open will show a existing pull request in a browser. Note: The — open flag is handy to find the URL of the provisioned wiki, but not specific to it.
Quirk
The provisioned wiki is strangely interwoven into Azure Repos but it works. Our next step is to figure out how to separate access (public for the provisioned wiki, private for the published one)… 🤔
