Skip to content

Commit 42e199e

Browse files
raykaoraykao
committed
feat(workflows): Lab docs explaining GHA workflows for automatic documentation and test generation using GitHub Copilot
- Added from https://github.com/sitoader/AgenticWorkflows
1 parent 953aba4 commit 42e199e

2 files changed

Lines changed: 325 additions & 0 deletions

File tree

‎labs/workflows/copilot.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`

‎labs/workflows/copilot.generate-tests.md‎

Lines changed: 187 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,187 @@
1+
# Generate Tests Workflow
2+
3+
**Workflow File**: [`.github/workflows/generate-tests.yml`](../../.github/workflows/generate-tests.yml)
4+
5+
This workflow analyzes commits for missing unit test coverage and automatically creates issues for Copilot to write the tests.
6+
7+
8+
## Overview
9+
10+
The Generate Tests workflow uses GitHub Copilot CLI to examine code changes and identify when new or modified code lacks corresponding unit tests. By automating test coverage analysis, teams can maintain high code quality without manual review overhead.
11+
12+
13+
## How It Works
14+
15+
```mermaid
16+
flowchart TD
17+
A[Push to Repository] --> B{Source files changed?}
18+
B -->|No| C[Skip workflow]
19+
B -->|Yes| D[Install Copilot CLI]
20+
D --> E[Load analyze-tests prompt]
21+
E --> F[Copilot analyzes code changes]
22+
F --> G{Tests missing?}
23+
G -->|No| H[Exit - Coverage adequate]
24+
G -->|Yes| I[Create GitHub Issue]
25+
I --> J[Assign Copilot Coding Agent]
26+
J --> K[Agent writes missing tests]
27+
K --> L[PR created with tests]
28+
```
29+
30+
### Step-by-Step Process
31+
32+
1. **Triggers on every push** (excluding non-source files)
33+
2. **Installs Copilot CLI** in the GitHub Actions runner
34+
3. **Loads the analyze-for-tests prompt** from [`.github/prompts/analyze-for-tests.prompt.md`](../../.github/prompts/analyze-for-tests.prompt.md)
35+
4. **Copilot checks if new code has corresponding tests**
36+
5. **If tests are missing** → Creates a GitHub issue and assigns Copilot
37+
6. **Copilot Coding Agent** then writes the missing tests
38+
39+
40+
## Criteria for Tests
41+
42+
### ✅ Tests ARE Needed
43+
44+
| Change Type | Example |
45+
|-------------|---------|
46+
| New Functions/Methods | `calculateDiscount()`, `validateOrder()` |
47+
| New Classes | `WarehouseService`, `OrderProcessor` |
48+
| Modified Business Logic | Changed calculation formulas, updated validation |
49+
| New API Endpoints | REST routes, GraphQL resolvers |
50+
| Error Handling Paths | Try/catch blocks, error conditions |
51+
52+
### ❌ Tests NOT Needed
53+
54+
| Change Type | Example |
55+
|-------------|---------|
56+
| Configuration Files | `tsconfig.json`, `package.json` |
57+
| Type Definitions Only | Interface declarations, type aliases |
58+
| Test Files Themselves | `*.test.ts`, `*.spec.ts` |
59+
| Documentation | README, comments, JSDoc |
60+
| Static Assets | Images, fonts, CSS |
61+
62+
63+
## Configuration
64+
65+
### Trigger Configuration
66+
67+
The workflow focuses on source code changes:
68+
69+
```yaml
70+
on:
71+
push:
72+
paths:
73+
- 'api/src/**/*.ts'
74+
- 'frontend/src/**/*.ts'
75+
- 'frontend/src/**/*.tsx'
76+
paths-ignore:
77+
- '**/*.test.ts'
78+
- '**/*.spec.ts'
79+
- '**/*.d.ts'
80+
```
81+
82+
### Required Secrets
83+
84+
| Secret | Description |
85+
|--------|-------------|
86+
| `COPILOT_CLI_TOKEN` | Personal Access Token with Copilot permissions |
87+
88+
89+
90+
## Prompt File
91+
92+
The workflow uses a specialized prompt to guide Copilot's analysis:
93+
94+
**Location**: [`.github/prompts/analyze-for-tests.prompt.md`](../../.github/prompts/analyze-for-tests.prompt.md)
95+
96+
This prompt instructs Copilot to:
97+
- Analyze the git diff for testable code changes
98+
- Identify functions, classes, and methods without test coverage
99+
- Evaluate if existing tests cover the modified code paths
100+
- Create a detailed issue listing specific tests to write
101+
102+
103+
## Example Issue Created
104+
105+
When the workflow detects missing tests, it creates an issue like:
106+
107+
```markdown
108+
## 🧪 Unit Tests Needed
109+
110+
**Commit**: def5678
111+
**Author**: @developer
112+
113+
### Code Requiring Tests
114+
115+
#### `api/src/routes/warehouse.ts`
116+
- [ ] `POST /` - Create warehouse endpoint
117+
- [ ] `GET /` - Get all warehouses
118+
- [ ] `GET /:id` - Get warehouse by ID
119+
- [ ] `GET /branch/:branchId` - Get warehouses by branch
120+
- [ ] `PUT /:id` - Update warehouse
121+
- [ ] `DELETE /:id` - Delete warehouse
122+
123+
### Test File Location
124+
`api/src/routes/warehouse.test.ts`
125+
126+
### Testing Framework
127+
Vitest with supertest for API testing
128+
129+
/assign @copilot
130+
```
131+
132+
133+
## Test Patterns Used
134+
135+
The Copilot Coding Agent follows established testing patterns in the codebase
136+
137+
### API Route Tests
138+
139+
```typescript
140+
import { describe, it, expect, beforeEach } from 'vitest';
141+
import request from 'supertest';
142+
import app from '../index';
143+
144+
describe('Warehouse Routes', () => {
145+
describe('GET /api/warehouses', () => {
146+
it('should return all warehouses', async () => {
147+
const response = await request(app).get('/api/warehouses');
148+
expect(response.status).toBe(200);
149+
expect(Array.isArray(response.body)).toBe(true);
150+
});
151+
});
152+
153+
describe('GET /api/warehouses/:id', () => {
154+
it('should return 404 for non-existent warehouse', async () => {
155+
const response = await request(app).get('/api/warehouses/99999');
156+
expect(response.status).toBe(404);
157+
});
158+
});
159+
});
160+
```
161+
162+
163+
## Troubleshooting
164+
165+
### Workflow Not Triggering
166+
167+
- Verify the push includes files matching the `paths` patterns
168+
- Ensure changes are not exclusively in `paths-ignore` patterns
169+
- Check that the workflow file exists in the default branch
170+
171+
### Copilot Not Detecting Missing Tests
172+
173+
- Review the generate-tests prompt for coverage criteria
174+
- Ensure the code changes are substantial enough to warrant tests
175+
- Check workflow logs for the analysis output
176+
177+
### Agent Writing Incorrect Tests
178+
179+
- Verify existing test patterns in the codebase are consistent
180+
- Check that the testing framework is correctly configured
181+
- Review the prompt for framework-specific instructions
182+
183+
### Tests Failing After Generation
184+
185+
- Run tests locally to identify issues
186+
- Check for missing imports or dependencies
187+
- Verify mock data matches the expected schema

0 commit comments

Comments
 (0)