Using Doctor in GitHub Actions for your documentation

February 19, 2021

Doctor is a tool that you can use to write your documentation in markdown and push it to your SharePoint. That way, you have one location to use and share the documentation in your company. In this article, I want to tell you more about how you can set up GitHub Actions to do automated documentation deployments.

Info I will use the doctor sample as the blueprint for this article.

The credentials

Right now, Doctor supports three types of authentications:

  1. Certificate authentication
  2. Username and password
  3. Device code

In GitHub Actions, you can only make use of the first two. Technically, the third is also a possibility, but in that case, it will not run fully automated.

Both of the options require similar steps. For certificate authentication, you will need to do some configuration first.

Important Things to do before you can use certificate authentication: prerequisites for certificate authentication.

Creating the workflow

In the project where you want to add the documentation, create the following directories: .github/workflows.

GitHub Actions workflow folder
GitHub Actions workflow folder

In the workflows folder, add a file named publish.yml (you can give it another name as well if you want). The file contents look as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
name: Publish your documentation

on:
  push:
    branches:
      - dev
      - main

jobs:
  build:
    runs-on: ubuntu-latest

    steps:
    - uses: actions/[email protected]
    - uses: actions/[email protected]
      with:
        node-version: '14'
        registry-url: https://registry.npmjs.org/
  
    - name: Install and publish
      run: |
        startClean=""
        # Check on which branch it is running
        if [[ ${GITHUB_REF} == "refs/heads/main" ]]; then
          startClean="--cleanStart --confirm"
        fi

        # Install doctor
        npm i @estruyf/doctor -g

        # Start doctor publish
        doctor publish --auth password --username "${{ secrets.USERNAME }}" --password "${{ secrets.PASSWORD }}" -u "${{ secrets.SITEURL }}" $startClean

As you can see, there is not a lot required to publish your documentation on SharePoint. The workflow automatically starts when you push your code to either the dev or main branch.

The workflow run task checks if the flow is running for the main branch. If that is the case, it will set some extra flags to specify to first do a clean-up on the site before publishing. Otherwise, it will just do page updates and not remove any pages.

Important If you want to make use of certificate authentication, you will need to --auth argument to certificate, remove the --username [username] argument, and add the --certificateBase64Encoded [certificateBase64Encoded] base64 string you created in the prerequisites for security authentication.

Configuring the secrets

Once you have the workflow in your project, go to GitHub to configure the secrets to use in the GitHub Action.

You do this by going to your project on GitHub:

  • Click on Settings of your project
  • Click on Secrets
  • Add for using password authentication, you need the USERNAME, PASSWORD, and SITEURL secrets.
The required GitHub secrets
The required GitHub secrets

Running your GitHub Actions workflow

Suppose the workflow and its secrets are in place. It is time to push your code. Once you did that, the Github Actions workflow will automatically start.

Publish your documentation flow in action
Publish your documentation flow in action

Happy documenting

Comments

comments powered by Disqus