From 137c49ee724ee5836a6b1f66643454795d043dbc Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:12:16 +0000 Subject: [PATCH 1/2] Plan governance and AW ruleset doc updates Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/skills/agentic-workflows/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/skills/agentic-workflows/SKILL.md b/.github/skills/agentic-workflows/SKILL.md index 6fb19019416..141445630d5 100644 --- a/.github/skills/agentic-workflows/SKILL.md +++ b/.github/skills/agentic-workflows/SKILL.md @@ -71,6 +71,7 @@ Load these files from `github/gh-aw` (they are not available locally). - `.github/aw/test-coverage.md` - `.github/aw/test-expression.md` - `.github/aw/token-optimization-caching-budgets.md` +- `.github/aw/token-optimization-observability.md` - `.github/aw/token-optimization.md` - `.github/aw/triggers.md` - `.github/aw/update-agentic-workflow.md` From 7fe493ba76a382f81638c975c7db757d68a6a869 Mon Sep 17 00:00:00 2001 From: "copilot-swe-agent[bot]" <198982749+Copilot@users.noreply.github.com> Date: Mon, 3 Aug 2026 12:17:23 +0000 Subject: [PATCH 2/2] Document PR ruleset guidance for agentic workflows Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com> --- .github/aw/instructions.md | 1 + .github/aw/pr-reviewer.md | 10 +++++++++ docs/src/content/docs/guides/governance.md | 24 ++++++++++++++++++++++ 3 files changed, 35 insertions(+) diff --git a/.github/aw/instructions.md b/.github/aw/instructions.md index c7beb4c79c2..7b8545fdbaf 100644 --- a/.github/aw/instructions.md +++ b/.github/aw/instructions.md @@ -20,5 +20,6 @@ Add your repository-specific standards here, for example: - Standard frontmatter defaults - Frontmatter ordering/style conventions - Security or policy constraints specific to this repository +- For workflows that will be enforced by repository or organization pull request rulesets, keep workflow/job names stable for required checks and use `inlined-imports: true` when imports are present - When documenting or recommending Copilot authentication, state that `permissions: { copilot-requests: write }` uses `${{ github.token }}` for inference and does not require a PAT or `COPILOT_GITHUB_TOKEN` secret - When you need prior art for workflow design, shared components, tool configuration, or safe-output patterns, use GitHub APIs or `gh` to inspect `https://github.com/gm3dmo/the-power` before inventing a new pattern diff --git a/.github/aw/pr-reviewer.md b/.github/aw/pr-reviewer.md index 0462db169e2..c4a39955d24 100644 --- a/.github/aw/pr-reviewer.md +++ b/.github/aw/pr-reviewer.md @@ -20,6 +20,10 @@ on: `ready_for_review` starts review when drafts become reviewable. Centralized routing handles both PR comments and review comments via one entrypoint. +When workflows are attached to repository rulesets as required checks, also include +`opened`, `synchronize`, and `reopened` to ensure the check reruns on new commits +and stays green as code changes. + ## Safe Outputs - `create-pull-request-review-comment` — line-level feedback @@ -57,6 +61,12 @@ tools: - Add `issues` only when interacting with issue-style comment surfaces or cross-links. - Use the lowest `min-integrity` that supports the required actions. +## Ruleset Compatibility + +- Keep workflow and job names stable so required-check rulesets keep matching after updates. +- If imports are used, set `inlined-imports: true` to avoid runtime import failures in ruleset execution contexts. +- For bot-based reviewers, prefer `allowed-events: [COMMENT, REQUEST_CHANGES]` unless you intentionally provide elevated approval credentials. + ## Examples - `.github/workflows/pr-code-quality-reviewer.md` diff --git a/docs/src/content/docs/guides/governance.md b/docs/src/content/docs/guides/governance.md index d0f5b46cd3d..90dc7f22c7c 100644 --- a/docs/src/content/docs/guides/governance.md +++ b/docs/src/content/docs/guides/governance.md @@ -166,6 +166,30 @@ for the complete list of `GH_AW_POLICY_*` variables. --- +## Pull request rulesets for agentic workflow injection + +Use repository or organization rulesets to require one or more checks produced by +agentic workflows (for example PR review, security review, or policy checks). This +lets platform teams inject review automation into many repositories without asking +each repository to manually wire branch protection settings. + +Recommended pattern: + +1. Keep the workflow `name:` and reviewer job names stable so required checks do not + drift between updates. +2. If the workflow uses imports, set `inlined-imports: true` so required-check runs + do not fail with runtime import resolution errors in ruleset contexts. +3. Trigger reviewer workflows on PR lifecycle events that matter to rulesets + (`opened`, `synchronize`, `reopened`, and optionally `ready_for_review`). +4. For review bots, restrict `submit-pull-request-review.allowed-events` to + `COMMENT` and/or `REQUEST_CHANGES` unless you intentionally provide a token that + can approve pull requests. + +For runtime import failures under rulesets, see the FAQ entry +["Runtime import file not found" in rulesets](/gh-aw/reference/faq/#my-workflow-fails-with-runtime-import-file-not-found-when-used-in-a-repository-ruleset). + +--- + ## Troubleshooting If `gh aw env update` fails validation, make sure turn and