How to: Copilot documents YAML files for Azure Pipelines and GitHub Actions

This article guides you in documenting any YAML files used in your pipelines for Azure Pipelines and GitHub Actions

Starting from the Copilot prompt in VSCode, you will have the possibility to create documentation for your YAML files used in automation processes in Azure Pipelines and GitHub Actions.

To do this, simply open the YAML file you want to document, include it in the Copilot context, and enter the following phrase in the prompt.

Create a markdown file based on this yaml to draw a flow to explain all stages and dependencies. 
Please also create a documentation to explain each stage.

The example above was based on the YAML available in the repository AITour-Exemplo05-MarkdownFlow.

trigger:
- none

pool:
  vmImage: ubuntu-latest

stages:
- stage: compliance
  displayName: Compliance Analysis
  jobs:
  - job: projectAnalysis
    displayName: Project Analysis
    steps:
    - script: echo "Stage compliance"

- stage: build
  dependsOn: 
  - compliance
  displayName: Build
  jobs:
  - job: functionBuild
    displayName: Function Build
    steps:
    - script: echo "Stage build"

- stage: qualityAnalysis
  dependsOn: 
  - build
  displayName: Code Quality Analysis
  jobs:
  - job:
    displayName: SonarQube
    steps:
    - script: echo "Stage quality"

- stage: qualityGate
  dependsOn:
  - qualityAnalysis
  displayName: Quality Gate
  jobs:
  - job:
    displayName: Quality Gate
    steps:
    - script: echo "Stage qualityGate"

- stage: artifactsUpload
  dependsOn:
  - build
  - qualityGate
  displayName: Artifacts Upload
  jobs:
  - job: artifactsUploadJob
    displayName: Artifacts Upload
    steps:
    - script: echo "Stage artifactsUpload"

- stage: deploy
  dependsOn:
  - build
  - artifactsUpload
  displayName: Deploy
  jobs:
  - job: functionDeploy
    displayName: Function Deploy
    steps:
    - script: echo "Stage deploy"

Notice that I also requested the prompt to use Mermaid syntax, which generated a diagram of the YAML flow, providing a visual representation of the entire process described in the file.

The result of the prompt is the creation of a Markdown file that outlines the entire YAML pipeline flow, along with a graphical representation of this flow.

# Azure Pipelines Workflow Documentation

## Workflow Diagram

```mermaid
graph TD
    A[Compliance Analysis] --> B[Build]
    B --> C[Code Quality Analysis]
    C --> D[Quality Gate]
    B --> E[Artifacts Upload]
    D --> E
    E --> F[Deploy]

## Stage Documentation
### 1. Compliance Analysis
- **Stage Name:** `compliance`
- **Description:** Performs compliance checks and ensures the code adheres to required standards.

### 2. Build
- **Stage Name:** `build`
- **Depends On:** `compliance`
- **Description:** Builds the project after compliance checks are completed.

### 3. Code Quality Analysis
- **Stage Name:** `qualityAnalysis`
- **Depends On:** `build`
- **Description:** Analyzes the code quality using tools like SonarQube.

### 4. Quality Gate
- **Stage Name:** `qualityGate`
- **Depends On:** `qualityAnalysis`
- **Description:** Ensures the code meets the quality gate criteria.

### 5. Artifacts Upload
- **Stage Name:** `artifactsUpload`
- **Depends On:** `build`, `qualityGate`
- **Description:** Uploads build artifacts for further use.

### 6. Deploy
- **Stage Name:** `deploy`
- **Depends On:** `build`, `artifactsUpload`
- **Description:** Deploys the application after all previous stages are successfully completed.

I have been increasingly using this documentation process, making it easier for everyone in an organization to understand the CI/CD processes that have been established.

Have fun! 😊