From YAML to Markdown: Auto-Document Your GitHub Actions Workflows

Keeping workflow documentation up to date is always a challenge. Every time a pipeline changes, the documentation risks becoming outdated — or worse, forgotten altogether.

To solve this, I created an extension that automatically generates Markdown documentation directly from your GitHub Actions YAML files. You can see the actual workflow script used for this project here: yml-generate-documentation

Until now, creating accurate documentation from GitHub Actions workflows meant writing, maintaining, and updating it by hand. But that changes with the arrival of GitHub Copilot CLI, now available in public preview.

According GitHub Copilot CLI documentation, you need to authenticate Copilot CLI using a Personal Access Token (PAT) with the “Copilot Requests” permission enabled.

Here’s how the flow works:

• Detect changes → Whenever a workflow YAML file is modified in your repository, the pipeline is triggered.

name: Auto Document Workflows

on:
  workflow_dispatch:
  
  push:
    paths:
      - ".github/workflows/*.yml"
      - ".github/workflows/*.yaml"
      - "!.github/workflows/generate-doc.yml"

• Run Copilot CLI → The extension uses GitHub Copilot CLI to analyze the updated YAML and Generate Markdown → A clear and structured Markdown file is created, describing all jobs, steps, and actions.

      - name: Install Copilot CLI
        run: npm install -g @github/copilot@latest

      - name: Get changed YML files
        id: changed
        run: |
          echo "Get YML files changed:"
          git fetch origin ${{ github.event.before }}
          files=$(git diff --name-only ${{ github.event.before }} ${{ github.sha }} | grep ".github/workflows/.*\.yml" || true)
          echo "changed_files=$files" >> $GITHUB_OUTPUT

      - name: Generating Documentation
        if: steps.changed.outputs.changed_files != ''
        run: |
          echo "Create docs folder to explain workflows."
          mkdir -p docs/workflows
          for f in ${{ steps.changed.outputs.changed_files }}; do
            outFile="docs/workflows/$(basename $f .yml).md"
            echo "📄 Processing $f"
            echo "📄 Generating doc on $outFile"
            copilot -p "Ignore any other files or workspace context. Use only the following content for analysis: $(cat "$f") Please explain in detail this workflow and describe stages, jobs and steps on markdown format. Create a mermaid that represent this workflow." > $outFile
            echo "✅ File generated $outFile"
          done
        env:
          GH_TOKEN: ${{ secrets.COPILOT_CLI }}

• Publish docs → The generated documentation is stored in your repository (for example, under docs/workflows/), so your team always has the latest version.

      - name: Commit & Push Docs
        if: steps.changed.outputs.changed_files != ''
        run: |
          git config user.name "github-actions[bot]"
          git config user.email "github-actions[bot]@users.noreply.github.com"
          git add docs/workflows
          git commit -m "docs: Refresh workflow documentation"
          git push

• The result? Your pipelines document themselves — making it easier for developers to understand the CI/CD flow without digging into YAML syntax.

In short: Copilot CLI’s public preview unlocks the AI capabilities needed to transform your pipelines into self-documenting assets.

Wishing everyone a good read!