_wiki-documentation.yaml

# This reusable workflow publishes Markdown docs to Github Wiki. Some manual
# setup is required before using it: enable Wiki in repository and create at
# least one page.

name: Publish Github Wiki documentation
on:
  workflow_call:
    inputs:
      release-tag:
        type: string
        required: true
        description: Tag name of the release used in the Wiki commit message
      release-url:
        type: string
        required: true
        description: URL to the release page used in the Wiki commit message
      artifact-name:
        type: string
        required: true
        description: Name of the build artifact from which to extract the Wiki pages
      git-user-name:
        type: string
        required: true
        description: Name of the git user who commits and pushes the Wiki change set
      git-user-email:
        type: string
        required: true
        description: Email address of said git user
    secrets:
      REPO_ACCESS_TOKEN:
        required: true

permissions:
  contents: read

jobs:
  publish-wiki:
    name: Publish Github Wiki
    if: github.event.repository.has_wiki == true
    runs-on: ubuntu-latest
    steps:

    - name: Harden Runner
      uses: step-security/harden-runner@0080882f6c36860b6ba35c610c98ce87d4e2f26f # v2.10.2
      with:
        egress-policy: audit # TODO: change to 'egress-policy: block' after couple of runs
        disable-sudo: true

    # Check out the repository's Wiki repo into the wiki/ folder. The token is required
    # only for private repositories.
    - name: Check out repository
      uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2
      with:
        token: ${{ secrets.REPO_ACCESS_TOKEN }}
        repository: ${{ format('{0}.wiki', github.repository) }}
        path: wiki

    # Download the build artifacts attached to this workflow run.
    - name: Download artifact
      uses: actions/download-artifact@fa0a91b85d4f404e444e00e005971372dc801d16 # v4.1.8
      with:
        name: ${{ inputs.artifact-name }}
        path: dist

    # Unpack the Markdown docs into the Wiki repository. Delete existing files first
    # to ensure that no stale files stay behind.
    - name: Copy Markdown documentation
      run: |
        mkdir docs/
        unzip -d docs/ "$(ls dist/*-docs-md.zip)"
        rm --recursive --force wiki/*
        cp --recursive --verbose --target-directory wiki/ docs/markdown/*

    # If there was any change to the Wiki then push the update.
    - name: Push to Wiki
      run: |
        cd wiki/
        if [ -n "$(git status --porcelain)" ]; then
          git add .
          git config --global user.name "$USER_NAME"
          git config --global user.email "$USER_EMAIL"
          git commit --message "$WIKI_COMMIT_MESSAGE"
          git push
        fi
      env:
        USER_NAME: ${{ inputs.git-user-name }}
        USER_EMAIL: ${{ inputs.git-user-email }}
        WIKI_COMMIT_MESSAGE: |
          docs: update for ${{ inputs.release-tag }}

          Refs: ${{ github.sha }}
          Link: ${{ inputs.release-url }}