Building a Per-Repo Wiki: Automating Documentation with GitHub Actions

Building a per-repo wiki that actually gets read

Engineer Vineeth N Krishnan developed a documentation workflow to stop being the ‘human shortcut’ for team deployment questions. The system utilizes the hidden .wiki.git repository structure that exists for every GitHub repository but often remains unused.

Why This Matters

Technical documentation often fails not because it is missing, but because it exists outside the developer’s primary workflow, leading to trust erosion when READMEs go stale. By treating documentation as code within a wiki/ folder, teams can apply PR reviews and version control to operational knowledge, ensuring that the ‘single source of truth’ is updated alongside the codebase rather than rotting in a separate UI.

Key Insights

• GitHub Wikis are separate git repositories accessible via the .wiki.git suffix, allowing for standard git clone and push operations.
• The rsync —delete command is critical in CI/CD pipelines to ensure the published wiki does not become a graveyard of deleted or outdated pages.
• Sparse checkouts in GitHub Actions allow workflows to pull only the documentation directory, optimizing performance for large-scale repositories.
• The ‘Answer, then write’ habit transforms Slack support threads into permanent documentation assets, reducing the cost of repeated developer interruptions.

Working Examples

GitHub Action to sync a local wiki/ folder to the repository’s hidden wiki git repo on every merge to main.

name: Publish Wiki
on:
  push:
    branches:
      - main
    paths:
      - 'wiki/**'
      - '.github/workflows/wiki-publish.yml'
permissions:
  contents: write
jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code repo
        uses: actions/checkout@v6
        with:
          sparse-checkout: |
            wiki
          sparse-checkout-cone-mode: false
      - name: Clone wiki repo
        env:
          GH_TOKEN: ${{ secrets.WIKI_TOKEN || secrets.GITHUB_TOKEN }}
          REPO: ${{ github.repository }}
        run: |
          git clone "https://x-access-token:${GH_TOKEN}@github.com/${REPO}.wiki.git" wiki-remote
      - name: Sync wiki content
        run: |
          rsync -av --delete --exclude='.git' wiki/ wiki-remote/
      - name: Commit and push
        working-directory: wiki-remote
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
          git add -A
          git commit -m "docs(wiki): sync from ${GITHUB_SHA:0:7}"
          git push origin HEAD

Practical Applications

• Use case: Onboarding new developers by placing architecture and setup docs directly in the repo they are assigned to, reducing initial Slack pings.
• Pitfall: Using the default GITHUB_TOKEN often results in permission failures; a Personal Access Token (PAT) with repo-write scope is required for reliable wiki pushes.
• Use case: Implementing PR-reviewed documentation where senior engineers can catch stale facts or architectural inaccuracies before they are published.
• Pitfall: Over-engineering page hierarchy on day one; successful wikis grow organically from three core pages: Home, Setup, and Deployment.

References:

• https://dev.to/vineethnkrishnan/building-a-per-repo-wiki-that-actually-gets-read-1kca