Skip to content

Commit bb7c8ba

Browse files
Copilotpelikhan
Copilot
and
pelikhan
committed
Add maintainer workflow for gh-aw upgrades
Co-authored-by: pelikhan <[email protected]>
1 parent 8b89bd3 commit bb7c8ba

File tree

3 files changed

+165
-0
lines changed

3 files changed

+165
-0
lines changed

‎README.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,6 +27,9 @@ A sample family of reusable [GitHub Agentic Workflows](https://githubnext.github
2727
- [🧪 Daily Test Coverage Improver](docs/daily-test-improver.md) - Improve test coverage by adding meaningful tests to under-tested areas
2828
- [⚡ Daily Performance Improver](docs/daily-perf-improver.md) - Analyze and improve code performance through benchmarking and optimization
2929

30+
### Maintenance Workflows
31+
- [🔧 Maintainer](docs/maintainer.md) - Upgrade workflows to the latest version of gh-aw
32+
3033
> [!WARNING] The workflows that help with coding tasks should be installed with caution and used only experimentally, then disabled. While the tasks are executed within GitHub Actions and have no access to secrets, they still operate in an environment where outward network requests are allowed. This means untrusted inputs such as issue descriptions, comments, and code could potentially be exploited to direct the models to access external content that in turn could be malicious. Pull requests and other outputs must be reviewed very carefully before merging.
3134
3235
## 💬 Share Feedback

‎docs/maintainer.md‎

Lines changed: 86 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,86 @@
1+
# 🔧 Maintainer Workflow
2+
3+
> For an overview of all available workflows, see the [main README](../README.md).
4+
5+
The [maintainer workflow](../workflows/maintainer.md?plain=1) helps keep your agentic workflows up to date by automatically upgrading them to the latest version of gh-aw. It fetches the latest changes from the gh-aw repository, attempts to recompile all workflows, and either creates a pull request with the updates or an issue if compilation errors occur.
6+
7+
## Installation
8+
9+
```bash
10+
# Install the 'gh aw' extension
11+
gh extension install githubnext/gh-aw
12+
13+
# Add the Maintainer workflow to your repository
14+
gh aw add githubnext/agentics/maintainer --pr
15+
```
16+
17+
This creates a pull request to add the workflow to your repository. After merging the PR and syncing to main, you can start a run of this workflow immediately by running:
18+
19+
```bash
20+
gh aw run maintainer
21+
```
22+
23+
**Mandatory Checklist**
24+
25+
* [ ] I am a repository admin or have sufficient permissions, and am happy for the safe-outputs portion of this workflow to create pull requests or issues in the repository.
26+
27+
* [ ] I have enabled "Allow GitHub Actions to create and approve pull requests" in the repository settings under "Actions > General"
28+
29+
* [ ] If in a fork, I have enabled "GitHub Actions" and "GitHub Issues" in the fork repository settings
30+
31+
* [ ] I will review all pull requests very carefully and monitor the repository.
32+
33+
## What it does
34+
35+
1. **Fetches latest gh-aw changes**: Retrieves the CHANGELOG.md or release notes from the `githubnext/gh-aw` repository to understand new features, breaking changes, and migration instructions.
36+
37+
2. **Installs latest gh-aw**: Upgrades the gh-aw CLI extension to the latest version using the GitHub token.
38+
39+
3. **Attempts recompilation**: Tries to recompile all workflows in the `workflows/` directory with the new gh-aw version.
40+
41+
4. **Fixes compilation errors**: If errors occur, analyzes them using the changelog and documentation, then attempts to fix the workflow files.
42+
43+
5. **Creates outputs**:
44+
- **Success**: Creates a pull request with upgraded workflows and any necessary fixes
45+
- **Failure**: Creates an issue documenting the compilation errors and attempted fixes
46+
47+
## Configuration
48+
49+
This workflow requires no configuration and works out of the box. It will process all workflow markdown files in the `workflows/` directory.
50+
51+
## What it reads from GitHub
52+
53+
- Repository contents and workflow files
54+
- CHANGELOG.md from the `githubnext/gh-aw` repository
55+
- Release information and documentation from gh-aw
56+
57+
## What it creates
58+
59+
- Creates pull requests with upgraded workflows (if successful)
60+
- Creates issues documenting upgrade failures (if compilation errors persist)
61+
- Makes file changes to workflow files to fix compatibility issues
62+
- May generate `.lock.yml` files during compilation
63+
- Requires `contents: write`, `pull-requests: write`, and `issues: write` permissions
64+
65+
## Human in the loop
66+
67+
- Review pull requests created by this workflow to understand what changed
68+
- Test the upgraded workflows before merging
69+
- Investigate issues created by the workflow if compilation fails
70+
- Manually fix complex migration issues that the workflow couldn't handle
71+
- Disable or uninstall the workflow if not needed regularly
72+
73+
## When to run
74+
75+
- Run this workflow when you know a new version of gh-aw has been released
76+
- Run it periodically (e.g., monthly) to stay up to date
77+
- Run it before making other workflow changes to ensure compatibility
78+
- Trigger manually via workflow_dispatch when needed
79+
80+
## Troubleshooting
81+
82+
If the workflow creates an issue instead of a PR:
83+
1. Review the issue to understand what compilation errors occurred
84+
2. Check the gh-aw changelog for migration instructions
85+
3. Manually update the affected workflows based on the guidance
86+
4. Re-run the maintainer workflow to verify the fixes work

‎workflows/maintainer.md‎

Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
on:
3+
workflow_dispatch:
4+
5+
permissions: read-all
6+
7+
network: defaults
8+
9+
safe-outputs:
10+
create-pull-request:
11+
draft: false
12+
create-issue:
13+
title-prefix: "${{ github.workflow }}"
14+
15+
tools:
16+
github:
17+
toolset: [all]
18+
edit: true
19+
web-fetch:
20+
bash: [ ":*" ]
21+
22+
timeout_minutes: 30
23+
24+
---
25+
26+
# Agentic Workflow Maintainer
27+
28+
Your name is "${{ github.workflow }}". Your job is to upgrade the workflows in the GitHub repository `${{ github.repository }}` to the latest version of gh-aw.
29+
30+
## Steps to follow:
31+
32+
1. **Fetch the latest gh-aw changes**:
33+
- Use the GitHub tools to fetch the CHANGELOG.md or release notes from the `githubnext/gh-aw` repository
34+
- Review and understand the interesting changes, breaking changes, and new features in the latest version
35+
- Pay special attention to any migration guides or upgrade instructions
36+
37+
2. **Install the latest gh-aw CLI extension**:
38+
- Run `gh extension install githubnext/gh-aw || gh extension upgrade githubnext/gh-aw` to install or upgrade to the latest version
39+
- Verify the installation by running `gh aw version` to check the current version
40+
41+
3. **Check the current workflows**:
42+
- Run `gh aw version` on the workflows directory to see the current versions
43+
- Identify which workflows exist in the `workflows/` directory
44+
45+
4. **Attempt to recompile the workflows**:
46+
- Clean up any existing `.lock.yml` files: `find workflows -name "*.lock.yml" -type f -delete`
47+
- Run `gh aw compile --validate` on each workflow file in the `workflows/` directory
48+
- Note any compilation errors or warnings
49+
50+
5. **Fix compilation errors if they occur**:
51+
- If there are compilation errors, analyze them carefully
52+
- Review the gh-aw changelog and new documentation you fetched earlier
53+
- Identify what changes are needed in the workflow files to make them compatible with the new version
54+
- Make the necessary changes to the workflow markdown files to fix the errors
55+
- Re-run `gh aw compile --validate` to verify the fixes work
56+
- Iterate until all workflows compile successfully or you've exhausted reasonable fix attempts
57+
58+
6. **Create appropriate outputs**:
59+
- **If all workflows compile successfully**: Create a pull request with the title "Upgrade workflows to latest gh-aw version" containing:
60+
- All updated workflow files
61+
- Any generated `.lock.yml` files
62+
- A detailed description of what changed, referencing the gh-aw changelog
63+
- A summary of any manual fixes that were needed
64+
65+
- **If there are compilation errors you cannot fix**: Create an issue with the title "Failed to upgrade workflows to latest gh-aw version" containing:
66+
- The specific compilation errors you encountered
67+
- What you tried to fix them
68+
- Links to relevant sections of the gh-aw changelog or documentation
69+
- The version of gh-aw you were trying to upgrade to
70+
71+
## Important notes:
72+
- Always check the gh-aw changelog first to understand breaking changes
73+
- Test each fix by running `gh aw compile --validate` before moving to the next error
74+
- Include context and reasoning in your PR or issue descriptions
75+
- If you create a PR, make sure it includes all necessary changes for the workflows to compile
76+

0 commit comments

Comments
 (0)