Skip to content

Commit 815d627

Browse files
sitoadersitoader
committed
Added docs
1 parent 32598ca commit 815d627

File tree

4 files changed

+411
-0
lines changed

4 files changed

+411
-0
lines changed

‎.github/workflows/copilot-setup-steps.yml‎

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
name: "Copilot Setup Steps"
2+
3+
# Allows you to test the setup steps from your repository's "Actions" tab
4+
on: workflow_dispatch
5+
6+
jobs:
7+
# The job MUST be called `copilot-setup-steps` or it will not be picked up by Copilot
8+
copilot-setup-steps:
9+
runs-on: ubuntu-latest
10+
# Set the permissions to the lowest permissions possible needed for *your steps*. Copilot will be given its own token for its operations.
11+
permissions:
12+
# If you want to clone the repository as part of your setup steps, for example to install dependencies, you'll need the `contents: read` permission. If you don't clone the repository in your setup steps, Copilot will do this for you automatically after the steps complete.
13+
contents: read
14+
# You can define any steps you want, and they will run before the agent starts.
15+
# If you do not check out your code, Copilot will do this for you.
16+
steps:
17+
- name: Checkout code
18+
uses: actions/checkout@v4
19+
20+
- name: Set up Node.js
21+
uses: actions/setup-node@v4
22+
with:
23+
node-version: "22"
24+
cache: "npm"
25+
26+
- name: Install JavaScript dependencies
27+
run: npm ci

‎README.md‎

Lines changed: 59 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,59 @@
1+
# Agentic DevOps with GitHub Copilot
2+
3+
Agentic workflows with GitHub Actions & Copilot: generate-docs, generate-tests, and beyond
4+
5+
6+
7+
| Workflow | Trigger | Description |
8+
|----------|---------|-------------|
9+
| [Generate Docs](docs/workflows/generate-docs.md) | Push | Analyzes commits and creates documentation issues |
10+
| [Generate Tests](docs/workflows/generate-tests.md) | Push | Identifies missing unit tests and creates issues |
11+
12+
---
13+
14+
## 🚀 Getting Started
15+
16+
### Prerequisites
17+
18+
- GitHub repository with **GitHub Copilot** enabled
19+
- **Copilot Coding Agent** enabled for your organization/repository
20+
- A **Personal Access Token (PAT)** with Copilot permissions
21+
22+
### Step 1: Create a Fine-Grained Personal Access Token
23+
24+
The Copilot CLI requires authentication via a Personal Access Token with specific permissions.
25+
26+
1. Visit [https://github.com/settings/personal-access-tokens/new](https://github.com/settings/personal-access-tokens/new)
27+
28+
2. Configure your token:
29+
- **Token name**: `Copilot CLI Token` (or any descriptive name)
30+
- **Expiration**: Set as appropriate for your security policies
31+
- **Repository access**: Select the repositories where you'll use the workflows
32+
33+
3. Under **"Permissions"**, click **"Account permissions"** and enable:
34+
- **Copilot Requests** — Required for Copilot CLI to function
35+
36+
4. Click **"Generate token"** and copy the token immediately (you won't see it again!)
37+
38+
### Step 2: Add the Token as a Repository Secret
39+
40+
1. Go to your repository → **Settings** → **Secrets and variables** → **Actions**
41+
2. Click **"New repository secret"**
42+
3. Add:
43+
- **Name**: `COPILOT_CLI_TOKEN`
44+
- **Value**: Paste your PAT from Step 1
45+
4. Click **"Add secret"**
46+
47+
### Step 3: Enable Copilot Coding Agent
48+
49+
Ensure the Copilot Coding Agent is enabled:
50+
1. Go to your repository → **Settings** → **Copilot** → **Coding Agent**
51+
2. Enable **"Allow Copilot to open pull requests"**
52+
53+
### Step 4: Verify Setup
54+
55+
Make a small code change and push. The workflows should:
56+
1. Install Copilot CLI
57+
2. Analyze your commit
58+
3. Create issues if documentation/tests are needed
59+
4. Assign Copilot to resolve the issues automatically

‎docs/workflows/generate-docs.md‎

Lines changed: 138 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Generate Documentation Workflow
2+
3+
**Workflow File**: [`.github/workflows/generate-docs.yml`](../../.github/workflows/generate-docs.yml)
4+
5+
## Overview
6+
7+
The Generate Documentation workflow leverages GitHub Copilot CLI to analyze code changes and automatically creates documentation when necessary. Instead of relying on developers to remember to update docs, this agentic workflow handles it autonomously.
8+
9+
10+
## How It Works
11+
12+
```mermaid
13+
flowchart TD
14+
A[Push to Repository] --> B{Excluded files only?}
15+
B -->|Yes| C[Skip workflow]
16+
B -->|No| D[Install Copilot CLI]
17+
D --> E[Load analyze-commit prompt]
18+
E --> F[Copilot analyzes commit diff]
19+
F --> G{Documentation needed?}
20+
G -->|No| H[Exit - No action needed]
21+
G -->|Yes| I[Create GitHub Issue]
22+
I --> J[Assign Copilot Coding Agent]
23+
J --> K[Agent implements documentation]
24+
K --> L[PR created with docs]
25+
```
26+
27+
### Step-by-Step Process
28+
29+
1. **Triggers on every push** (excluding docs and markdown files)
30+
2. **Installs Copilot CLI** in the GitHub Actions runner
31+
3. **Loads the analyze-for-docs prompt** from [`.github/prompts/analyze-for-docs.prompt.md`](../../.github/prompts/analyze-for-docs.prompt.md)
32+
4. **Copilot examines the commit diff** using MCP tools
33+
5. **If documentation is needed** → Creates a GitHub issue and assigns Copilot
34+
6. **Copilot Coding Agent** then implements the documentation
35+
36+
37+
## Criteria for Documentation
38+
39+
### ✅ Documentation IS Needed
40+
41+
| Change Type | Example |
42+
|-------------|---------|
43+
| Public APIs | New REST endpoints, GraphQL mutations |
44+
| Functions/Classes | Exported functions, public class methods |
45+
| Complex Logic | Algorithms, business rules, data transformations |
46+
| Architectural Changes | New services, modified data flow |
47+
| Breaking Changes | API contract changes, removed features |
48+
49+
### ❌ Documentation NOT Needed
50+
51+
| Change Type | Example |
52+
|-------------|---------|
53+
| Minor Refactoring | Variable renames, code reorganization |
54+
| Formatting | Whitespace, linting fixes |
55+
| Trivial Typo Fixes | Comment typos, string corrections |
56+
| Internal Implementation | Private methods, internal helpers |
57+
58+
59+
## Configuration
60+
61+
### Trigger Configuration
62+
63+
The workflow excludes certain paths to avoid unnecessary runs:
64+
65+
```yaml
66+
on:
67+
push:
68+
paths-ignore:
69+
- 'docs/**'
70+
- '**/*.md'
71+
- '.github/workflows/**'
72+
```
73+
74+
### Required Secrets
75+
76+
| Secret | Description |
77+
|--------|-------------|
78+
| `COPILOT_CLI_TOKEN` | Personal Access Token with Copilot permissions |
79+
80+
---
81+
82+
## Prompt File
83+
84+
The workflow uses a specialized prompt to guide Copilot's analysis:
85+
86+
**Location**: [`.github/prompts/analyze-for-docs.prompt.md`](../../.github/prompts/analyze-for-docs.prompt.md)
87+
88+
This prompt instructs Copilot to:
89+
- Analyze the git diff of the latest commit
90+
- Evaluate changes against documentation criteria
91+
- Determine if public-facing code was added or modified
92+
- Create a well-structured issue if documentation is warranted
93+
94+
95+
## Example Issue Created
96+
97+
When the workflow detects documentation is needed, it creates an issue like:
98+
99+
```markdown
100+
## 📚 Documentation Needed
101+
102+
**Commit**: abc1234
103+
**Author**: @developer
104+
105+
### Changes Requiring Documentation
106+
107+
- New `/api/warehouses` endpoint added
108+
- `Warehouse` model with 10 properties
109+
- CRUD operations for warehouse management
110+
111+
### Suggested Documentation
112+
113+
1. Update API documentation with new endpoints
114+
2. Add Warehouse model to data model docs
115+
3. Include usage examples
116+
117+
/assign @copilot
118+
```
119+
120+
121+
122+
## Troubleshooting
123+
124+
### Workflow Not Triggering
125+
126+
- Verify the push includes files outside the `paths-ignore` patterns
127+
- Check that the workflow file exists in the default branch
128+
129+
### Copilot Not Creating Issues
130+
131+
- Ensure `COPILOT_CLI_TOKEN` secret is configured
132+
- Verify the token has `Copilot Requests` permission
133+
- Check workflow logs for authentication errors
134+
135+
### Agent Not Implementing Documentation
136+
137+
- Confirm Copilot Coding Agent is enabled in repository settings
138+
- Verify the issue is properly assigned to `@copilot`

0 commit comments

Comments
 (0)