diff --git a/starters/README.md b/starters/README.md new file mode 100644 index 00000000000..f29ca4e5f08 --- /dev/null +++ b/starters/README.md @@ -0,0 +1,37 @@ +# GitHub Agentic Workflow Starters + +Tiny but useful starter workflows — one per Ops pattern — to help you get started with GitHub Agentic Workflows. Copy any file to `.github/workflows/` in your repository, adjust the placeholders, then run `gh aw compile ` to generate the lock file. + +## Pattern Summary + +| Pattern | Starter | Trigger | What It Does | Why It's Useful | +|---------|---------|---------|--------------|-----------------| +| **[ChatOps](https://github.github.com/gh-aw/patterns/chat-ops/)** | [`chat-ops/pr-explain.md`](chat-ops/pr-explain.md) | `/explain` in PR comment | Summarizes PR changes in plain English | Non-engineers understand code changes without reading diffs | +| **[IssueOps](https://github.github.com/gh-aw/patterns/issue-ops/)** | [`issue-ops/first-contributor-welcome.md`](issue-ops/first-contributor-welcome.md) | Issue or PR opened | Greets first-time contributors with links to contributing guides | Reduces friction and drop-off for open-source newcomers | +| **[DailyOps](https://github.github.com/gh-aw/patterns/daily-ops/)** | [`daily-ops/stale-pr-nudge.md`](daily-ops/stale-pr-nudge.md) | Daily schedule | Comments on PRs with no activity for 7+ days | Prevents reviews from silently stalling in the backlog | +| **[LabelOps](https://github.github.com/gh-aw/patterns/label-ops/)** | [`label-ops/close-wontfix.md`](label-ops/close-wontfix.md) | `wontfix` label applied | Closes the issue with a contextual explanation | Automates backlog housekeeping without boilerplate comments | +| **[DataOps](https://github.github.com/gh-aw/patterns/data-ops/)** | [`data-ops/weekly-contribution-report.md`](data-ops/weekly-contribution-report.md) | Weekly schedule (Monday 9 AM) | Posts a merged-PR digest with top contributors to Discussions | Gives teams a recurring pulse on contribution activity | +| **[DispatchOps](https://github.github.com/gh-aw/patterns/dispatch-ops/)** | [`dispatch-ops/codebase-qa.md`](dispatch-ops/codebase-qa.md) | `workflow_dispatch` with a question | Answers natural-language questions about the codebase and documents the answer as an issue | Turns one-off Slack questions into persistent documentation | +| **[ProjectOps](https://github.github.com/gh-aw/patterns/project-ops/)** | [`project-ops/board-router.md`](project-ops/board-router.md) | Issue opened or labeled | Adds issues to a project board and sets Priority / Status fields by label | Eliminates manual triage clicks to keep boards accurate | +| **[WorkQueueOps](https://github.github.com/gh-aw/patterns/workqueue-ops/)** | [`workqueue-ops/checklist-processor.md`](workqueue-ops/checklist-processor.md) | `workflow_dispatch` with an issue number | Processes unchecked items in a GitHub issue checklist one batch at a time | Drives long-running migrations or audits across many runs | +| **[MultiRepoOps](https://github.github.com/gh-aw/patterns/multi-repo-ops/)** | [`multi-repo-ops/cross-repo-issue-mirror.md`](multi-repo-ops/cross-repo-issue-mirror.md) | `upstream` label applied | Mirrors an issue to a companion repository for cross-team tracking | Keeps upstream maintainers informed without leaving your repo | +| **[BatchOps](https://github.github.com/gh-aw/patterns/batch-ops/)** | [`batch-ops/bulk-stale-labeler.md`](batch-ops/bulk-stale-labeler.md) | Weekly schedule (Monday 3 AM) | Labels up to 20 inactive issues as `stale` each run | Scales stale-issue hygiene across large backlogs incrementally | + +## Usage + +```bash +# 1. Copy a starter to your workflow directory +cp starters/chat-ops/pr-explain.md .github/workflows/pr-explain.md + +# 2. Edit placeholders (e.g. YOUR-ORG, project URLs, secrets) +# then compile to generate the lock file +gh aw compile pr-explain + +# 3. Trigger it +gh aw run pr-explain +``` + +> **Placeholders to replace** +> - `YOUR-ORG/YOUR-UPSTREAM-REPO` in `multi-repo-ops/cross-repo-issue-mirror.md` +> - `https://github.com/orgs/YOUR-ORG/projects/1` in `project-ops/board-router.md` +> - Secret names prefixed with `GH_AW_` that require a PAT or cross-repo token diff --git a/starters/batch-ops/bulk-stale-labeler.md b/starters/batch-ops/bulk-stale-labeler.md new file mode 100644 index 00000000000..aadd4dccf7e --- /dev/null +++ b/starters/batch-ops/bulk-stale-labeler.md @@ -0,0 +1,23 @@ +--- +name: Bulk Stale Labeler +description: Apply a "stale" label to issues that have had no activity for 30 days, processed in weekly batches. +on: + schedule: + - cron: "0 3 * * 1" + workflow_dispatch: +permissions: + contents: read + issues: read +tools: + github: + toolsets: [issues] +safe-outputs: + add-labels: + max: 20 + add-comment: + max: 1 +--- + +Calculate the date 30 days ago and search for open issues with no recent activity using `search_issues` with query `is:issue is:open -label:stale updated:COMPUTED-DATE` to fetch this week's merged pull requests. +Group results by author and identify the top contributor by merge count. +Create a Discussion with a markdown table listing PR number, title, author, and a "Top Contributor" callout at the top. diff --git a/starters/dispatch-ops/codebase-qa.md b/starters/dispatch-ops/codebase-qa.md new file mode 100644 index 00000000000..b2499f7a24b --- /dev/null +++ b/starters/dispatch-ops/codebase-qa.md @@ -0,0 +1,25 @@ +--- +name: Codebase Q&A +description: Answer natural-language questions about the codebase on demand using repository context. +on: + workflow_dispatch: + inputs: + question: + description: "What do you want to know about the codebase?" + required: true + type: string +permissions: + contents: read +tools: + github: + toolsets: [repos] +safe-outputs: + create-issue: + title-prefix: "[qa] " + labels: [documentation] + max: 1 +--- + +Answer the following question about the codebase: "${{ inputs.question }}". +Explore relevant source files and README documents to gather context before answering. +Create an issue with the question as the title and your detailed answer as the body so the response is permanently documented. diff --git a/starters/issue-ops/first-contributor-welcome.md b/starters/issue-ops/first-contributor-welcome.md new file mode 100644 index 00000000000..f3c77d6a14d --- /dev/null +++ b/starters/issue-ops/first-contributor-welcome.md @@ -0,0 +1,20 @@ +--- +name: First Contributor Welcome +description: Greet first-time contributors when they open their first issue or pull request. +on: + issues: + types: [opened] + pull_request: + types: [opened] +permissions: + contents: read + issues: read + pull-requests: read +safe-outputs: + add-comment: + max: 1 +--- + +If `author_association` is `FIRST_TIME_CONTRIBUTOR`, `FIRST_TIMER`, or `NONE` and the author is not a bot, post a warm welcome comment thanking them for their contribution. +Include links to CONTRIBUTING.md and CODE_OF_CONDUCT.md, and offer to answer any questions they might have. +Otherwise call `noop` — existing contributors do not need a welcome message. diff --git a/starters/label-ops/close-wontfix.md b/starters/label-ops/close-wontfix.md new file mode 100644 index 00000000000..a99aa907b3a --- /dev/null +++ b/starters/label-ops/close-wontfix.md @@ -0,0 +1,17 @@ +--- +name: Close Won't Fix +description: Close issues automatically when the wontfix label is applied and post a brief explanation. +on: + label_command: wontfix +permissions: + contents: read + issues: read +safe-outputs: + add-comment: + max: 1 + close-issue: +--- + +Post a polite comment explaining that the issue is being closed as won't fix, summarizing the decision in one sentence based on the issue title and body. +Thank the reporter for raising it and suggest they open a new issue if circumstances change. +Then close the issue. diff --git a/starters/multi-repo-ops/cross-repo-issue-mirror.md b/starters/multi-repo-ops/cross-repo-issue-mirror.md new file mode 100644 index 00000000000..1054cd51ff2 --- /dev/null +++ b/starters/multi-repo-ops/cross-repo-issue-mirror.md @@ -0,0 +1,20 @@ +--- +name: Cross-Repo Issue Mirror +description: Mirror issues labeled "upstream" to a companion repository for cross-team tracking. +on: + label_command: upstream +permissions: + contents: read + issues: read +safe-outputs: + github-token: ${{ secrets.GH_AW_CROSS_REPO_PAT }} + create-issue: + target-repo: "YOUR-ORG/YOUR-UPSTREAM-REPO" + title-prefix: "[mirror] " + labels: [upstream-mirror] + max: 1 +--- + +Read the triggering issue's title, body, and labels, then create a mirror issue in the upstream repository. +Include a link back to the original issue and a one-sentence summary of the problem. +Do not include any personally identifiable information from the issue author. diff --git a/starters/project-ops/board-router.md b/starters/project-ops/board-router.md new file mode 100644 index 00000000000..7dda619835b --- /dev/null +++ b/starters/project-ops/board-router.md @@ -0,0 +1,19 @@ +--- +name: Issue Board Router +description: Add newly opened issues to a GitHub Project board and set the Priority field based on labels. +on: + issues: + types: [opened, labeled] +permissions: + contents: read + issues: read +safe-outputs: + update-project: + project: https://github.com/orgs/YOUR-ORG/projects/1 + github-token: ${{ secrets.GH_AW_PROJECT_GITHUB_TOKEN }} + max: 1 +--- + +Add the triggering issue to the project board defined above. +Set the Priority field to `High` if the issue has a `priority-high` or `critical` label, `Low` if it has `good first issue`, and `Medium` for everything else. +If the issue has a `bug` label also set the Status field to `In Triage`. diff --git a/starters/workqueue-ops/checklist-processor.md b/starters/workqueue-ops/checklist-processor.md new file mode 100644 index 00000000000..fa7c8077232 --- /dev/null +++ b/starters/workqueue-ops/checklist-processor.md @@ -0,0 +1,29 @@ +--- +name: Checklist Processor +description: Process a queue of work items stored as checkboxes in a GitHub issue, checking each off as it completes. +on: + workflow_dispatch: + inputs: + queue_issue: + description: "Issue number containing the checklist queue" + required: true + type: string +permissions: + contents: read + issues: read +tools: + github: + toolsets: [issues] +safe-outputs: + update-issue: + body: true + add-comment: + max: 1 +concurrency: + group: checklist-${{ inputs.queue_issue }} + cancel-in-progress: false +--- + +Read issue #${{ inputs.queue_issue }} and find all unchecked checkboxes in its body. +Process up to 5 unchecked items — for each one, perform the described action, then check it off by updating the issue body. +When done, add a comment summarizing how many items were completed and how many remain.