docs: comprehensive guide for maintaining repos with agentic workflows at scale by Copilot · Pull Request #26073 · github/gh-aw

Copilot · 2026-04-13T17:09:56Z

Summary

Adds docs/src/content/docs/guides/maintaining-repos.md — a comprehensive how-to guide for repository maintainers running agentic workflows at scale. The guide is structured around a two-mechanism safety model and uses repo-assist as the primary entry point.

Closes #26072

Key Design Decisions

Two-mechanism safety model — The guide frames the entire maintainer experience around two complementary controls:
- Safe-outputs control what the agent can do (outputs) — principle of least privilege for actions like labeling, commenting, creating PRs
- Integrity filtering controls what content the agent sees (inputs) — filtering by author trust level and merge status
Repo-assist first — Rather than covering features in isolation, the guide leads with repo-assist as the recommended triage layer, then layers on safe-outputs and integrity as the maintainer scales
Debugging as a first-class section — Covers AI-assisted debugging via /agent agentic-workflows and Copilot CLI commands (gh aw audit, gh aw logs), plus six common failure patterns with targeted fixes

Content Outline

Repo-Assist as Your Triage Layer — What it does, minimal workflow example, routing to downstream agents
Controlling Workflow Outputs with Safe-Outputs — Output types table, paired examples (repo-assist vs code-fix agent), principle of least privilege
Controlling Workflow Inputs with Integrity Filtering — Decision guidance by workflow type (merged/approved/unapproved/none), trusted-users, approval-labels, blocked-users, centralized management via GitHub variables
Reactions as Trust Signals — MCPG ≥ v0.2.18 opt-in, endorsement/disapproval reactions, proxy-only limitation
Scaling Strategies — Token budget impact, rate-limit, concurrency controls, allowed-repos scoping
Debugging Failed Workflows — /agent agentic-workflows for AI-assisted debugging, gh aw audit/gh aw logs CLI commands, common failure patterns (missing tools, auth failures, integrity filtering, safe-output violations, token exhaustion, MCP server issues)
Worked Examples — Public open-source repo (repo-assist → approval-labels → code fix), inner-source (trusted-users via org variable), high-security (min-integrity: merged + blocked-users)

Files Changed

File	Description
`docs/src/content/docs/guides/maintaining-repos.md`	New comprehensive maintainer guide
`.github/aw/actions-lock.json`	Updated from main merge
`pkg/workflow/data/action_pins.json`	Updated from main merge

Agent-Logs-Url: https://github.com/github/gh-aw/sessions/a064782d-41c0-4598-a610-56b542b18186 Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

lpcox · 2026-04-13T17:21:15Z

@copilot make sure that repo-assist is the primary entry point and that guidance framed as making repo-assist work for a (primarily open-source) maintainer

lpcox · 2026-04-13T17:23:25Z

@copilot resolve the merge conflicts in this pull request also make sure that safeoutputs is presented as the primary safety mechanism for regulating workflow outputs whereas integrity filtering is the primary safety mechanism for regulating workflow inputs.

github-actions · 2026-04-13T17:23:39Z

Hey @Copilot and @lpcox 👋 — great work getting the maintaining-repos guide drafted! This is a comprehensive piece covering integrity filtering decision guidance, reactions as trust signals, scaling strategies, debugging workflows, and three well-structured worked examples (public, inner-source, high-security). It fills a clear gap in the docs and cross-links cleanly to the existing reference pages.

A few things to tidy up before marking this ready for review:

Checklist items are still unchecked — docs/src/content/docs/guides/maintaining-repos.md exists on the branch and appears fully written (covers all seven checklist items), but the PR description still shows every task as [ ]. Review each item against the actual content and check them off once confirmed.
Remove the [WIP] prefix and promote from draft — once the checklist is verified, rename the title and mark the PR ready so maintainers can merge.
Diff discrepancy — GitHub's PR diff API currently reports only a 10-line actions-lock.json reordering (moving the ghcr.io/github/gh-aw-mcpg:v0.2.19 entry to its alphabetically correct position). The new guide file doesn't appear in the reported diff view, even though it exists on the branch in commit 7f9e493e. This may cause automated review tooling to miss the primary change — worth double-checking that the commit history is structured as expected and the file addition is properly attributed.

If you'd like a hand finishing this off, here's a ready-to-use agent prompt:

In the PR branch `copilot/add-comprehensive-guide-agentic-workflows` of `github/gh-aw`:

1. Open `docs/src/content/docs/guides/maintaining-repos.md` and verify it covers each of the following items:
   - Integrity filtering deep dive with decision guidance
   - Reactions as trust signals (MCPG >= v0.2.18)
   - Scaling strategies (repo-assist triage layer, token budgets, rate limiting)
   - Debugging failed workflows (CLI commands and `/agent agentic-workflows`)
   - Common failure patterns with diagnostic steps
   - At least 3 worked examples (public, inner-source, high-security)
   - Cross-links to existing reference pages

2. For each section that is complete, update the corresponding checkbox in the PR description from `[ ]` to `[x]`.

3. If any sections are incomplete or missing, add the missing content following the Markdown + frontmatter style used by sibling guides such as `docs/src/content/docs/guides/audit-with-agents.md` and `docs/src/content/docs/guides/getting-started-mcp.md`.

4. Verify the `actions-lock.json` change (reordering of `ghcr.io/github/gh-aw-mcpg:v0.2.19`) is intentional and not an artifact of the agent session.

5. Once all checklist items are verified and checked off, remove the `[WIP]` prefix from the PR title and mark the PR as ready for review.

Generated by Contribution Check · ● 2.6M · ◷

…ntry point Agent-Logs-Url: https://github.com/github/gh-aw/sessions/88b88ad7-34c7-40e1-a18c-6f0c2b32075a Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Copilot · 2026-04-13T17:27:07Z

@copilot make sure that repo-assist is the primary entry point and that guidance framed as making repo-assist work for a (primarily open-source) maintainer

Done in 73645f8. The guide now opens with repo-assist as the primary entry point — the intro frames the problem from an open-source maintainer's perspective, repo-assist is the first concrete thing shown (with a full workflow example), and integrity filtering is explained afterward as the mechanism that makes repo-assist route work safely. The worked examples section also leads with the public OSS scenario (repo-assist → code fix agent) rather than the more generic examples.

…ety mechanism Co-authored-by: lpcox <15877973+lpcox@users.noreply.github.com>

Copilot · 2026-04-13T17:36:08Z

@copilot resolve the merge conflicts in this pull request also make sure that safeoutputs is presented as the primary safety mechanism for regulating workflow outputs whereas integrity filtering is th...

Done in e012958. Merge conflicts resolved (stale gh-aw-mcpg:v0.2.17 pin removed from both actions-lock.json and action_pins.json). The guide now opens with an explicit two-mechanism safety model — safe-outputs as the primary mechanism for controlling what the agent can do (outputs), and integrity filtering as the primary mechanism for controlling what content the agent sees (inputs). A dedicated "Controlling Workflow Outputs with Safe-Outputs" section was added before the integrity filtering section, covering the principle of least privilege, the full output type table, and paired examples. The "Related Documentation" section also lists Safe Outputs Reference first.

Copilot

Pull request overview

Adds a new maintainer-focused documentation guide for operating agentic workflows safely at scale (repo-assist + safe-outputs + integrity filtering), along with updated action pin/lock data from a main-branch merge.

Changes:

Introduces maintaining-repos.md guide structured around a two-mechanism safety model and maintainer workflows (triage, scaling, debugging, worked examples).
Updates action pin/lock JSON to include the gh-aw-mcpg:v0.2.19 image entry in the expected location.
Documents integrity reactions and operational debugging patterns (/agent agentic-workflows, gh aw audit, gh aw logs).

Show a summary per file

File	Description
`docs/src/content/docs/guides/maintaining-repos.md`	New comprehensive maintainer guide covering repo-assist, safe-outputs, integrity filtering, scaling, and debugging.
`.github/aw/actions-lock.json`	Syncs pinned MCPG image entry (`gh-aw-mcpg:v0.2.19`) position/content.
`pkg/workflow/data/action_pins.json`	Syncs pinned MCPG image entry (`gh-aw-mcpg:v0.2.19`) position/content.

Copilot's findings

Tip

Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comments suppressed due to low confidence (4)

docs/src/content/docs/guides/maintaining-repos.md:110

The safe-outputs list/table uses non-existent output types (e.g., label-issue, comment-issue, comment-pull-request). Please align the names with the actual safe output types (e.g., add-labels/remove-labels, add-comment, etc.) from the Safe Outputs reference so readers don’t copy invalid config.

| Safe-output | What it allows |
|------------|---------------|
| `label-issue` | Apply or remove labels on an issue |
| `comment-issue` | Post a comment on an issue |
| `comment-pull-request` | Post a comment on a pull request |

docs/src/content/docs/guides/maintaining-repos.md:145

The integrity-level descriptions here don’t match the reference definitions (notably, unapproved is CONTRIBUTOR/FIRST_TIME_CONTRIBUTOR, while none is the only level that includes NONE/FIRST_TIMER). Update this table (and any dependent guidance) to match the Integrity Filtering reference to avoid misconfiguration.

| Level | Who qualifies |
|-------|--------------|
| `merged` | PRs merged into the default branch; commits reachable from main |
| `approved` | Owners, members, collaborators; non-fork PRs on public repos; recognized bots (`dependabot`, `github-actions`) |
| `unapproved` | Contributors who have had a PR merged before; first-time contributors |

docs/src/content/docs/guides/maintaining-repos.md:53

This paragraph says min-integrity: unapproved allows repo-assist to see “external users, everyone”, but unapproved still filters out NONE/FIRST_TIMER authors. Either change the setting to none or update the description so it matches the actual integrity semantics.

`min-integrity: unapproved` allows repo-assist to see all community content — first-time contributors, external users, everyone. The `safe-outputs` block limits what repo-assist can do in response: it can only apply labels and post comments. Any other GitHub mutation (opening PRs, merging, closing issues) is blocked by the runtime, regardless of what the agent attempts.

docs/src/content/docs/guides/maintaining-repos.md:49

This prompt instructs the workflow to “consider assigning the Copilot coding agent”, but the workflow’s safe-outputs (even once renamed) only allow labeling/commenting. Either add the assign-to-agent safe output (and describe its limits), or remove the assignment instruction to keep the example internally consistent.

2. If the issue is a quality bug report with a clear reproduction, add the label `needs-investigation`.
3. If the issue is from a maintainer or collaborator, add `trusted-contributor` and consider assigning the Copilot coding agent to investigate.
4. If the issue appears to be spam or off-topic, add `invalid` and post a brief explanation comment.

Files reviewed: 3/3 changed files
Comments generated: 7

Copilot · 2026-04-13T17:47:15Z