Using GitHub Copilot AI for Documenting and Diagramming CI/CD Pipelines
Author - Abdul Rahman (Content Writer)
AI
3 Articles
Table of Contents
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.