Stakeholders can't read my Azure DevOps Wiki as Code docs

I’ve been using Azure DevOps for a very long time and since a few years I’ve been trying to use the Azure DevOps wiki. While you can just use the wiki editor to write plain text, I prefer to use the Markdown format as I have been doing for my blog as well (and even my notes since I switched to Obsidian).

Azure DevOps has two ways to create a project wiki: the classic wiki and Wiki as Code. The classic wiki is a simple WYSIWYG editor (and also backed by a hidden Git repository), while the Wiki as Code is a full separate Git repository next to your other project repositories.

While you could technically clone both and use your favorite editor, I prefer the latter as it allows the team to use the same pull request process to review and approve changes. After all, (technical) documentation is as important as code and should be treated as such.

The problem

Your corporate projects are typically private. Looking at the official documentation on wiki permissions, we notice that Stakeholders (product owner, project manager, CxO, …) can read the wiki, but only when it is provisioned as a classic wiki. They can’t read or edit code (nor code wiki pages).

Users with Stakeholder access in a private project can read provisioned wiki pages and view revisions, but they can’t edit. For example, Stakeholders can’t create, edit, reorder, or revert changes to project wiki pages. These permissions can’t be changed.

Stakeholders have zero access to read or edit published code wiki pages in private projects. For more information, see the Stakeholder access quick reference for project and code wikis.

There are several feedback tickets open for this topic, some of them going back for 5-6 years already. For example this one touches the capability to edit, but also the fact that Stakeholders can’t even read the wiki as code.

The workaround

I still want to keep the wiki as code, but I need to end up with a classic wiki that is readable by stakeholders. The solution is to use a pipeline to ‘abuse’ the fact that both are backed by a Git repository and push it to the classic wiki repository. This way, the wiki is still versioned and can be reviewed by the team, but the stakeholders can read it as well.

Wiki structure

I have done this with the release pipelines in the past, but nowadays you can easily define a pipeline in the repository itself.

A wiki repository is slightly different from a regular repository. Everything you push in the repository will be visible in the wiki, except for the .attachments folder. This folder typically contains all the images you have added to your wiki pages. And we can hide our pipeline in there as well. Since we have full control over this repository, I prefer to structure my images in subfolders too.

Create a pipeline

Simply create a new file azure-pipelines.yml and add the following content (don’t forget to correctly name your project and organization):

trigger:
- main

pool:
  vmImage: ubuntu-latest

resources:
  repositories:
    - repository: wiki
      type: git
      name: YourProject/YourProject.wiki

steps:
- checkout: self
  fetchDepth: 0
- checkout: wiki
  persistCredentials: true

- script: |
    cd ThisRepositoryName
    git config --global user.email "mywikipipeline@dev.azure.com"
    git config --global user.name "Project Documentation"

    git checkout main
    git -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" remote add wiki https://dev.azure.com/YourOrg/YourProject/_git/YourProject.wiki
    git -c http.extraheader="AUTHORIZATION: bearer $(System.AccessToken)" push wiki main:wikiMaster    
  displayName: Git Push

Note: We need to add a user name and email address to the Git configuration. This is required to be able to push to the wiki repository. This doesn’t have to be a real user or even a valid email address.

Security

Finally, go the published wiki’s security page and add the Project Build Service account and allow Contribute permissions. This is required to be able to push to the wiki repository.

Note: To prevent conflicts on the git push, it is advisable to remove any contribute permissions for the team members directly on the classic wiki.