👉🏼 Click here to Join I ❤️ .NET WhatsApp Channel to get 🔔 notified about new articles and other updates.
Using GitHub Copilot AI for Documenting and Diagramming CI/CD Pipelines

Using GitHub Copilot AI for Documenting and Diagramming CI/CD Pipelines

Author - Abdul Rahman (Content Writer)

AI

3 Articles

Improve

Table of Contents

  1. What we gonna do?
  2. Why we gonna do?
  3. How we gonna do?
  4. Summary

What we gonna do?

CI/CD pipelines are the backbone of modern software delivery, but documenting them can be tedious and error-prone. In this guide, I'll show you how to leverage GitHub Copilot to automatically generate and maintain comprehensive documentation and visual diagrams for your CI/CD workflows. This approach ensures your documentation stays in sync with your pipeline code while dramatically reducing the manual effort required to maintain it.

Why we gonna do?

Well-documented CI/CD pipelines are crucial for team understanding, onboarding, and troubleshooting. However, keeping documentation synchronized with constantly evolving workflows is challenging. As pipelines grow more complex with parallel jobs, conditional steps, and multiple deployment targets, the gap between documentation and reality widens.

By using GitHub Copilot to analyze your workflow files and generate Mermaid diagrams and documentation, you can:

  • Maintain 100% accuracy between workflow code and documentation
  • Visualize complex workflows with clear dependency paths
  • Instantly generate documentation for new or updated pipelines
  • Create standardized diagrams that follow consistent formatting rules
  • Improve team collaboration by ensuring everyone understands the pipeline

This approach transforms pipeline documentation from a tedious afterthought into an automatically maintained asset that brings genuine value to your development process.

How we gonna do?

Setting Up Your CI/CD Documentation System

Let's establish a systematic approach to documenting CI/CD pipelines with GitHub Copilot. I'll walk through each step using our ILoveDotNet project as a real-world example.

Step 1: Create a CI/CD Documentation Prompt

First, create a specialized prompt file that guides GitHub Copilot in analyzing your workflow files. Save this as ci-cd-documentation-prompt.md in your project:


# CI/CD Documentation & Diagramming Prompt

As an expert in CI/CD workflows and technical documentation, assist me with analyzing and documenting my GitHub Actions 
workflows using the following approaches:

## PERSONA
You are a skilled DevOps engineer and documentation specialist who can visualize complex CI/CD pipelines and create clear, 
accurate documentation that reflects the current state of the workflows.

## INSTRUCTIONS
Analyze my GitHub Actions workflow files to create visual representations and help maintain documentation that accurately 
reflects their current state.

## Task 1: Workflow Diagram Generation

Please perform the following tasks in sequence:

1. **Analyze Workflow Structure**
   - Examine the GitHub Actions workflow files in the .github/workflows directory
   - Identify all jobs, steps, and their dependencies
   - Understand trigger conditions and workflow dispatch events
   - Analyze conditional execution paths and parallel processes
   - Document deployment targets and artifact generation

2. **Create Visual Representation**
   - Show the workflow structure visually using Mermaid syntax
   - Create a comprehensive flowchart that includes:
     1. Trigger events (push, pull request, schedule, manual)
     2. Jobs and their relationships
     3. Key steps within each job
     4. Conditional paths using dotted lines
     5. Parallel processes using the & syntax
     6. Deployment targets and artifacts
   - Ensure the diagram uses valid Mermaid syntax with appropriate styling
   - Label all connections to explain dependencies and conditions

3. **Document Workflow Visually**
   - Create or update the CI/CD section in README.md
   - Include the Mermaid diagram with proper formatting
   - Add explanatory text for key workflow components
   - Highlight security checks, build processes, and deployment paths

4. **Track Workflow Changes**
   - Compare current workflow files with previous versions
   - Identify added or removed jobs, steps, or conditions
   - Update diagrams to accurately reflect the current state
   - Preserve diagram styling and formatting

## FORMAT
Provide results in markdown format with appropriate sections, code blocks, and Mermaid diagrams.
      

This prompt creates a persona for GitHub Copilot to follow with specific instructions for analyzing workflow files and generating accurate diagrams. It focuses on comprehensive workflow visualization including triggers, jobs, steps, and their dependencies.

Step 2: Analyze Your Workflow Files

With your prompt file ready, use GitHub Copilot Chat to analyze your workflow files:


Please analyze the workflow files in .github/workflows/ following the instructions in ci-cd-documentation-prompt.md. 
Generate a comprehensive Mermaid diagram that shows all jobs, steps, and dependencies.
      

Let's see how this works with our ILoveDotNet project's build-blazor-app.yml file:


name: build blazor app

on:
  push:
    branches:
      - main
    paths-ignore:
      - "**.md"
      - ".github/workflows/codeql.yml"
  pull_request:
    branches:
      - main
  schedule:
      - cron: '0 17 * * 0'
  workflow_dispatch:

jobs:
  blazor-app-ci-cd:
    name: Blazor App Build, Test and Deploy
    runs-on: ubuntu-latest
    permissions:
      contents: write
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup .NET
        env:
          DOTNET_NOLOGO: true
          DOTNET_CLI_TELEMETRY_OPTOUT: true
        uses: actions/setup-dotnet@v4
        with:
          dotnet-version: 9.0.x

      - name: Install .NET WASM Build Tools
        run: dotnet workload install wasm-tools

      - name: Restore npm dependencies
        run: npm install
        working-directory: ./CommonComponents
      
      # More steps...
      
      - name: Commit wwwroot to GitHub Pages
        if: ${{ github.actor != 'dependabot[bot]' && github.event_name != 'pull_request' }}
        uses: JamesIves/github-pages-deploy-action@v4
        with:
          BRANCH: gh-pages
          FOLDER: dist/Web/wwwroot
      

GitHub Copilot will analyze this workflow file and generate a Mermaid diagram that visualizes its structure. Here's what the output might look like:


```mermaid
flowchart TD
    %% Styling
    classDef trigger fill:#f96,stroke:#333,stroke-width:2px
    classDef job fill:#bbf,stroke:#333,stroke-width:2px
    classDef setup fill:#bfb,stroke:#333,stroke-width:1px
    classDef build fill:#fbf,stroke:#333,stroke-width:1px
    classDef test fill:#fbb,stroke:#333,stroke-width:1px
    classDef deploy fill:#bff,stroke:#333,stroke-width:1px
    
    %% Triggers
    Triggers([GitHub Action Triggers])
    Push[Push to main]
    PR[Pull Request to main]
    Schedule[Weekly Schedule]
    Manual[Manual Trigger]
    
    %% Jobs
    BlazorAppCICD[Blazor App Build, Test and Deploy]
    
    %% Setup steps
    Checkout[Checkout code]
    SetupDotNet[Setup .NET]
    InstallWASM[Install WASM tools]
    NPMInstall[Restore npm dependencies]
    VulnerabilityCheck[Checking Vulnerable npm Packages]
    RestoreDeps[Restore .NET dependencies]
    
    %% Build steps
    Format[Format code]
    BuildBlazor[Build Blazor project]
    
    %% Test steps
    InstallReportGen[Install Report Generator]
    RunTests[Run UI Tests]
    GenerateTestReport[Generate Test Report]
    UploadTestResults[Upload Test Results]
    
    %% Deploy steps
    PublishBlazor[Publish Blazor project]
    UploadArtifacts[Upload build artifacts]
    DeployToGitHubPages[Deploy to GitHub Pages]
    
    %% Connections
    Triggers --> Push & PR & Schedule & Manual
    Push & PR & Schedule & Manual --> BlazorAppCICD
    
    BlazorAppCICD --> Checkout --> SetupDotNet
    SetupDotNet --> InstallWASM
    Checkout --> NPMInstall --> VulnerabilityCheck
    InstallWASM & VulnerabilityCheck --> RestoreDeps --> Format --> BuildBlazor
    
    BuildBlazor --> InstallReportGen --> RunTests --> GenerateTestReport --> UploadTestResults
    
    UploadTestResults --> PublishBlazor --> UploadArtifacts
    UploadArtifacts --> DeployToGitHubPages
    
    %% Conditional path
    PR -.->|"skipped for pull requests"| DeployToGitHubPages
    
    %% Apply styles
    class Triggers,Push,PR,Schedule,Manual trigger
    class BlazorAppCICD job
    class Checkout,SetupDotNet,InstallWASM,NPMInstall,VulnerabilityCheck,RestoreDeps setup
    class Format,BuildBlazor build
    class InstallReportGen,RunTests,GenerateTestReport,UploadTestResults test
    class PublishBlazor,UploadArtifacts,DeployToGitHubPages deploy
```
      

Step 3: Create Detailed Documentation with the Diagram

Next, ask GitHub Copilot to create comprehensive documentation that incorporates the diagram:


Based on the workflow analysis, create a detailed CI/CD section for our README.md that explains the workflow stages,
dependencies between steps, and deployment paths. Include the Mermaid diagram with proper styling.
      

GitHub Copilot will generate comprehensive documentation that explains the workflow in detail:


## CI/CD Pipeline

Our continuous integration and deployment pipeline automates building, testing, and deploying the 
ILoveDotNet application. 
The pipeline is implemented using GitHub Actions and is defined in `.github/workflows/build-blazor-app.yml`.

### Workflow Triggers

The CI/CD pipeline can be triggered in several ways:
- **Push to main**: Automatically runs when changes are pushed to the main branch (excluding markdown files)
- **Pull Requests**: Runs on pull requests targeting the main branch
- **Weekly Schedule**: Runs every Sunday at 17:00 UTC to ensure dependencies are up-to-date
- **Manual Trigger**: Can be manually triggered through the GitHub Actions interface

### Pipeline Visualization

The following diagram illustrates the complete CI/CD workflow:

```mermaid
flowchart TD
    %% Styling
    classDef trigger fill:#f96,stroke:#333,stroke-width:2px
    classDef job fill:#bbf,stroke:#333,stroke-width:2px
    classDef setup fill:#bfb,stroke:#333,stroke-width:1px
    classDef build fill:#fbf,stroke:#333,stroke-width:1px
    classDef test fill:#fbb,stroke:#333,stroke-width:1px
    classDef deploy fill:#bff,stroke:#333,stroke-width:1px
    
    %% Triggers
    Triggers([GitHub Action Triggers])
    Push[Push to main]
    PR[Pull Request to main]
    Schedule[Weekly Schedule]
    Manual[Manual Trigger]
    
    %% Jobs and steps...
```

### Key Pipeline Stages

#### 1. Setup
The setup phase prepares the environment by:
- Checking out the code
- Setting up .NET and Node.js environments
- Installing required tools and dependencies
- Checking for vulnerable npm packages

#### 2. Build
The build phase:
- Verifies code formatting
- Builds the Blazor WebAssembly application

#### 3. Testing
The testing phase:
- Runs UI tests
- Generates code coverage reports
- Uploads test results as artifacts

#### 4. Deployment
The deployment phase:
- Publishes the Blazor application
- Uploads build artifacts
- Deploys to GitHub Pages (only for pushes to main, not pull requests)
      

Step 4: Tracking Workflow Changes

As your CI/CD pipeline evolves, keeping documentation in sync is crucial. GitHub Copilot makes it easy to track and document changes:


I've updated comments and configuration in our workflow file. Please analyze the changes and update the 
documentation to reflect the current workflow structure.
      

GitHub Copilot will analyze the workflow file and provide updated documentation:


## Workflow Evolution

The ILoveDotNet CI/CD pipeline has evolved to focus on optimizing the build and deployment process for our 
Blazor WebAssembly application. The current workflow is designed around a single job that handles the complete 
pipeline from setup to deployment.

### Key Optimizations

- **Conditional Deployment**: GitHub Pages deployment only occurs on pushes to main branch and excludes 
dependabot changes
- **Caching Strategy**: Optimized dependencies restoration for faster builds
- **Automated Testing**: Comprehensive test reporting with code coverage
- **Commented Alternatives**: Preserved references to alternative approaches for future consideration

These improvements ensure our CI/CD process remains robust while being easy to maintain and understand.
      

Step 5: Document Conditional Logic

For advanced scenarios, you can ask GitHub Copilot to explain complex conditional logic in your workflow:


Explain the conditional logic used in our GitHub Pages deployment step. What conditions must be met for 
deployment to occur?
      

GitHub Copilot will analyze the workflow structure and provide detailed explanations:


## Deployment Conditions Analysis

The ILoveDotNet project uses conditional deployment to ensure GitHub Pages is only updated under specific 
circumstances:

```yaml
- name: Commit wwwroot to GitHub Pages
  if: ${{ github.actor != 'dependabot[bot]' && github.event_name != 'pull_request' }}
  uses: JamesIves/github-pages-deploy-action@v4
  with:
    BRANCH: gh-pages
    FOLDER: dist/Web/wwwroot
```

This deployment step has two conditions that must both be satisfied:

1. **Not Triggered by Dependabot**: The `github.actor != 'dependabot[bot]'` condition prevents automated 
dependency update PRs from deploying to production. This is a security measure that ensures human review 
before updates affect the live site.

2. **Not a Pull Request**: The `github.event_name != 'pull_request'` condition ensures deployments only 
happen on direct pushes to the main branch, not during PR validation. This prevents feature branches from 
deploying to production prematurely.

When both conditions are met (typically on manual or scheduled pushes to the main branch), the GitHub Pages 
deployment action executes, publishing the Blazor WebAssembly application to production.
      

Step 6: Create Guidelines for CI/CD Documentation

Finally, establish guidelines for maintaining CI/CD documentation to ensure consistency:


Create a set of guidelines for maintaining our CI/CD documentation, focusing on Mermaid diagram conventions,
styling rules, and best practices for documenting workflow changes.
      

GitHub Copilot will generate comprehensive guidelines for your team:


# Guidelines for CI/CD Workflow Documentation

This document provides specific instructions for maintaining CI/CD workflow documentation in our project.

## Mermaid Diagram Conventions

### Layout Structure
- Use top-down flowcharts with `flowchart TD` for all CI/CD diagrams
- Group related steps using subgraphs where appropriate
- Position triggers at the top, jobs in the middle, and deployment steps at the bottom

### Connection Types
- Use solid lines (`-->`) for direct dependencies
- Use dotted lines (`-.->`) for conditional paths
- Use the `&` operator for parallel processes: `A & B --> C`
- Add labels to connections that have conditions: `A -->|"only on main"| B`

### Node Styling
- Use consistent color coding:
  - Triggers: Orange (#f96)
  - Jobs: Light blue (#bbf)
  - Setup steps: Green (#bfb)
  - Build steps: Purple (#fbf)
  - Test steps: Red (#fbb)
  - Deploy steps: Cyan (#bff)
- Apply styles using class definitions at the top of the diagram
- Use consistent shapes: triggers as rounded rectangles, jobs as rectangles

## Documentation Best Practices

1. **Always validate diagrams** before committing them
2. **Update documentation when workflow changes**
3. **Include explanatory text** for each major pipeline section
4. **Document conditional logic** that affects workflow execution
5. **Keep a change log** of significant workflow modifications

Following these guidelines ensures our CI/CD documentation remains clear, accurate, and valuable to the team.
      

Real-World Example: Documentation Best Practices

Let's look at a practical example of how documentation best practices can be applied when working with workflow files:

When documenting our build-blazor-app.yml workflow, it's important to accurately represent its structure and behavior:


## Workflow Structure

The ILoveDotNet CI/CD pipeline uses a single comprehensive job that handles all aspects of the build, test, 
and deployment process. This design choice provides several advantages:

1. **Simplified Dependency Management**: All steps share the same environment and workspace
2. **Sequential Execution Control**: Each phase (setup, build, test, deploy) runs in a controlled order
3. **Consolidated Logging**: All related logs appear in a single job context for easier troubleshooting
4. **Resource Efficiency**: No duplicate checkout or setup steps required across multiple jobs

The workflow includes conditional deployment logic to ensure GitHub Pages is only updated when appropriate 
conditions are met.
      

This documentation accurately reflects the actual structure of our workflow, making it clear that we use a single job design pattern rather than parallel jobs. Maintaining this accuracy is essential for team understanding.

Summary

Using GitHub Copilot to document and diagram CI/CD pipelines transforms a traditionally tedious task into an automated, accurate process. By creating a well-structured prompt and incorporating it into your workflow, you ensure your pipeline documentation always reflects the current state of your actual workflow files.

This approach offers significant benefits: consistently up-to-date documentation, standardized visual representations, tremendous time savings, and improved communication across your team. As your CI/CD pipelines evolve, your documentation evolves with them, maintaining its value as a reference point for the entire team.

For complex projects with multiple jobs, parallel processes, and conditional steps, maintaining accurate documentation manually would be nearly impossible. With GitHub Copilot, it becomes not just possible, but straightforward. Start implementing this approach in your projects today, and watch as your CI/CD pipeline documentation transforms from a burden into an asset that genuinely supports your development process.

👉🏼 Click here to Join I ❤️ .NET WhatsApp Channel to get 🔔 notified about new articles and other updates.
  • AI
  • Copilot
  • GitHub
  • Documenting
  • CI
  • CD
  • Pipelines
  • Diagram