Repository navigation
docs(integrations): modernise the gh-aw consumer for token-based inference - #4
Conversation
…rence Everything here was verified by installing gh-aw v0.83.4 and compiling, not by reading documentation. The compiler validates: unknown keys, wrong value types and keys at the wrong nesting level all fail it, so a clean compile is evidence. Two real defects in the shipped workflow, both reported by the compiler: - `toolsets: [default]` includes the `pull_requests` toolset, which requires `pull-requests: read`. Without it the workflow compiled with a warning and would have failed at run time for anyone who installed it. - `engine: copilot` was documented as needing "no extra secret on GitHub-hosted runners". That was wrong. Copilot inference was billed per seat and needed a COPILOT_GITHUB_TOKEN PAT. Since June 2026 `permissions: copilot-requests: write` bills it to the organisation through the built-in GITHUB_TOKEN — which the workflow now declares, and which the compiler itself suggests. That change is narrower than it sounds, and the docs now say so. It removes the PAT for *inference*. It does not remove the one for CI: a pull request opened with GITHUB_TOKEN does not trigger pull_request or push workflows, so the agent's PR arrives with no checks unless a GH_AW_CI_TRIGGER_TOKEN secret exists. Two tokens, two problems, one of them solved. It also only works where the org has enabled "Allow use of Copilot CLI billed to the organization"; elsewhere it falls back to the PAT. Also added, all compiler-verified: `roles:` pinned so triage-only accounts cannot spend AI credits by labelling an issue, `max-ai-credits` and `max-daily-ai-credits` well under gh-aw's 5000 AIC default, `source:` so `gh aw update` works, `strict:`, and `description:`. New ORGANIZATIONS.md covers the part that does not scale by copying files: a central repository, `gh aw add`/`update`/`deploy`, version pinning, a shared policy pulled in with `imports:`, the admin prerequisites that fail confusingly (allowed-actions list, Copilot CLI billing policy), GitHub App auth for cross-repo writes, and the consequence GitHub states plainly — billing to the org means user-level inference budgets no longer apply, so the credit caps are what replaces them. A CI job now compiles the shipped workflow and fails on warnings, which closes the "gh aw compile is unverified" open question. The open question is replaced rather than deleted: compiling proves the configuration is valid, not that the prompt works, and nobody has watched a real run yet. The gate's first version grepped the log for "warning" and failed every build, because the success line is "0 error(s), 0 warning(s)". It now asserts that summary exactly, and was checked against the old file, the new file, and a deliberately invalid one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01JrA2MbAG4JsRH9Eo4ALUNH
📝 WalkthroughWalkthroughThe pull request adds CI compilation for shipped gh-aw workflows, expands workflow permissions and cost controls, configures CI triggering for agent-created pull requests, and documents setup, validation, authentication, and organization-wide deployment. Changesgh-aw workflow integration
Estimated code review effort: 3 (Moderate) | ~25 minutes Suggested reviewers: 🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 9
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (2)
AGENTS.md (2)
11-13: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winPin the gh-aw extension to v0.83.4.
The consumer runbooks mention gh-aw v0.83.4, but the setup still uses
gh extension upgrade aw, which installs the latest release and can compile the workflow with a different compiler. Use the versioned install path such asgh extension install github/gh-aw@v0.83.4, then keepgh aw versionandgh aw doctoras follow-up checks.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 11 - 13, Update the gh-aw setup instructions to install the pinned v0.83.4 release instead of running the unversioned `gh extension upgrade aw` command. Preserve `gh aw version` and `gh aw doctor` as follow-up validation checks.
22-26: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winPin the standalone
gh-awinstaller fallback.The fallback installer defaults to
latest, which can compile the workflow with a differentgh-awedition than CI. Passv0.83.4explicitly inintegrations/gh-aw/AGENTS.md.Proposed fix
-curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash +curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash -s -- v0.83.4🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@AGENTS.md` around lines 22 - 26, Update the standalone gh-aw fallback installer instructions in the gh-aw guidance to pass version v0.83.4 explicitly instead of relying on the latest default, matching the CI-pinned edition.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.github/workflows/ci.yml:
- Around line 167-169: Pin every gh-aw installer invocation to v0.83.4 instead
of relying on latest: update .github/workflows/ci.yml lines 167-169,
integrations/gh-aw/AGENTS.md lines 11-13, and integrations/gh-aw/AGENTS.md lines
22-26. Keep the existing installation paths and subsequent setup steps unchanged
while ensuring all documented and CI installations use the same pinned version.
- Line 158: Update the actions/checkout@v4 step in the CI workflow to disable
credential persistence by setting persist-credentials to false before the remote
installer runs. Leave the checkout source and surrounding job steps unchanged.
In `@docs/GOTCHAS.md`:
- Around line 146-149: Update the introductory qualification in the “GitHub
Agentic Workflows (gh-aw)” section to distinguish claims verified by gh aw
compile from runtime behavior and documented behavior. Do not imply that CI
triggering, billing/PAT fallback, Copilot inference permissions, or prompt
output were confirmed by compilation; preserve the gh-aw v0.83.4 version
context.
In `@integrations/gh-aw/ORGANIZATIONS.md`:
- Around line 144-166: Correct the “Set defaults centrally” section to describe
GH_AW_DEFAULT_MAX_AI_CREDITS and GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS as
downstream gh-aw runtime defaults that may be overridden by compiled or imported
workflow values, not organization-wide floors. Clarify that
GH_AW_DEFAULT_TIMEOUT_MINUTES is read by the compiler process and only applies
when the compile job passes it into the compiler environment; update the gh aw
env guidance accordingly.
- Around line 192-208: Update the “Staged” description in the rollout section to
state that safe-output write operations are skipped, not all API calls. Preserve
that it writes a step summary of intended actions and clarify that it does not
create permanent GitHub resources.
- Around line 61-93: Revise the imports explanation after the
err2issue-safety.md example to describe imported settings as validated policy
defaults rather than unoverrideable guarantees. State that gh-aw validates
required permissions, while main-workflow values can override imported
permissions, safe-outputs, caps, and other supported fields; retain the
commit-SHA caching and lockfile reproducibility details.
In `@integrations/gh-aw/README.md`:
- Around line 120-125: Update the max-daily-ai-credits documentation comment in
the Cost ceilings example to describe it as a workflow-wide cap aggregating
completed runs over the rolling 24-hour window, and remove the misleading
per-user qualification.
In `@integrations/gh-aw/workflows/err2issue-autofix.md`:
- Around line 35-39: Align the Copilot authentication documentation across both
affected sites: in integrations/gh-aw/workflows/err2issue-autofix.md lines
35-39, replace the automatic per-seat fallback claim with distinct org-billing
guidance using copilot-requests: write and PAT-mode guidance that removes that
permission and configures COPILOT_GITHUB_TOKEN; in integrations/gh-aw/README.md
lines 106-118, remove the automatic fallback claim and document personal/PAT
usage as a separate workflow configuration.
- Around line 77-83: The documentation at
integrations/gh-aw/workflows/err2issue-autofix.md:77-83 and
integrations/gh-aw/README.md:187-191 incorrectly says GITHUB_TOKEN prevents CI
workflows from starting. Update both references to explain that token-triggered
pull_request workflows require approval and do not run automatically, and
present the GH_AW_CI_TRIGGER_TOKEN PAT empty-commit path as the supported
non-approval-required CI trigger.
---
Outside diff comments:
In `@AGENTS.md`:
- Around line 11-13: Update the gh-aw setup instructions to install the pinned
v0.83.4 release instead of running the unversioned `gh extension upgrade aw`
command. Preserve `gh aw version` and `gh aw doctor` as follow-up validation
checks.
- Around line 22-26: Update the standalone gh-aw fallback installer instructions
in the gh-aw guidance to pass version v0.83.4 explicitly instead of relying on
the latest default, matching the CI-pinned edition.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro Plus
Run ID: f3d97e0e-9fd7-43f3-b93e-348dccc3b8cf
📒 Files selected for processing (8)
.github/workflows/ci.ymlAGENTS.mddocs/GOTCHAS.mdintegrations/README.mdintegrations/gh-aw/AGENTS.mdintegrations/gh-aw/ORGANIZATIONS.mdintegrations/gh-aw/README.mdintegrations/gh-aw/workflows/err2issue-autofix.md
| if: github.event.action != 'edited' | ||
| runs-on: ubuntu-latest | ||
| steps: | ||
| - uses: actions/checkout@v4 |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Relevant workflow context:"
sed -n '145,190p' .github/workflows/ci.yml 2>/dev/null || true
echo
echo "All checkout usages in workflows:"
rg -n "actions/checkout|persist-credentials|gh-aw|pull" .github/workflows . 2>/dev/null | sed -n '1,200p'
echo
echo "Package/source mentions of gh-aw compiler versions:"
rg -n "gh-aw|v0\.83\.4|compiler|compiler summary|summary" . 2>/dev/null | sed -n '1,220p'Repository: matthiasbigl/err2issue
Length of output: 27837
🌐 Web query:
actions/checkout v4 persist-credentials default true README
💡 Result:
In actions/checkout v4, the persist-credentials input defaults to true [1][2]. When set to true (the default), the action configures the authentication token or SSH key into the local git configuration [3][4]. This allows subsequent steps in the same job to execute authenticated git commands using those credentials [3][4]. The action automatically removes these credentials during the post-job cleanup phase [3][4]. If you wish to opt out of this behavior, you can explicitly set persist-credentials to false [3][5]. This is often done when you need to manage credentials manually or want to ensure that no repository credentials remain in the git config during the execution of other steps [6].
Citations:
- 1: https://github.com/actions/checkout/blob/v4/action.yml
- 2: https://github.com/actions/checkout/blob/v4.1.1/action.yml
- 3: https://github.com/actions/checkout/blob/v4/README.md
- 4: https://github.com/actions/checkout/tree/v4.3.1
- 5: https://github.com/actions/checkout/blob/main/README.md
- 6: https://spacelift.io/blog/github-actions-checkout
Disable checkout credential persistence before running the remote installer.
actions/checkout@v4 persists the default GITHUB_TOKEN in local git config by default, while the next step fetches and executes shell code from the gh-aw main branch. This job does not need authenticated Git operations.
Proposed fix
- uses: actions/checkout@v4
+ with:
+ persist-credentials: false📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - uses: actions/checkout@v4 | |
| - uses: actions/checkout@v4 | |
| with: | |
| persist-credentials: false |
🧰 Tools
🪛 zizmor (1.28.0)
[warning] 158-158: credential persistence through GitHub Actions artifacts (artipacked): does not set persist-credentials: false
(artipacked)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/ci.yml at line 158, Update the actions/checkout@v4 step in
the CI workflow to disable credential persistence by setting persist-credentials
to false before the remote installer runs. Leave the checkout source and
surrounding job steps unchanged.
Source: Linters/SAST tools
| curl -sL https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh | bash | ||
| AW="$HOME/.local/share/gh/extensions/gh-aw/gh-aw" | ||
| "$AW" version |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== files =="
git ls-files .github/workflows/ci.yml integrations/gh-aw/AGENTS.md
echo "== CI snippets =="
cat -n .github/workflows/ci.yml | sed -n '150,180p'
echo "== AGENTS snippets =="
cat -n integrations/gh-aw/AGENTS.md | sed -n '1,40p'
echo "== gh-aw references =="
rg -n "gh-aw|gh aw|0\.83\.4|install-gh-aw|upgrade aw|extension upgrade" .Repository: matthiasbigl/err2issue
Length of output: 13115
🌐 Web query:
github gh-aw install-gh-aw.sh version argument latest release
💡 Result:
The install-gh-aw.sh script for the GitHub Agentic Workflows (gh-aw) CLI extension supports an optional version argument to specify which release to install [1][2]. If no version is provided as an argument, the script defaults to "latest" [1][2]. The usage syntax for the script is:./install-gh-aw.sh [version] [options] Examples of usage: - Install the latest version:./install-gh-aw.sh [1][2] - Install a specific version:./install-gh-aw.sh v1.0.0 [1][2] When the version is set to "latest" (either explicitly or by omission), the script resolves the most recent release tag using the GitHub API to determine the appropriate download URL [1][3]. For specific version arguments (e.g., v0.64.5), it attempts to download the asset directly from the corresponding GitHub release tag [1][2]. Additionally, users can install specific versions via the GitHub CLI extension manager using the @ syntax: gh extension install github/gh-aw@v0.64.5 [4] top_results: [1][2][3][4]
Citations:
- 1: https://raw.githubusercontent.com/github/gh-aw/main/install-gh-aw.sh
- 2: https://github.com/github/gh-aw/blob/main/install-gh-aw.sh
- 3: Harden latest-install download path in
install-gh-aw.shwith versioned fallback github/gh-aw#37564 - 4: https://github.github.com/gh-aw/reference/releases/
Pin the configured gh-aw installation paths to v0.83.4.
These docs claim the workflow compiles with gh-aw v0.83.4, but the CI job and the standalone installer block both invoke install-gh-aw.sh without a version, which defaults to latest. Pass v0.83.4 there and keep the other setup steps on the same pinned tool.
📍 Affects 2 files
.github/workflows/ci.yml#L167-L169(this comment)integrations/gh-aw/AGENTS.md#L11-L13integrations/gh-aw/AGENTS.md#L22-L26
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.github/workflows/ci.yml around lines 167 - 169, Pin every gh-aw installer
invocation to v0.83.4 instead of relying on latest: update
.github/workflows/ci.yml lines 167-169, integrations/gh-aw/AGENTS.md lines
11-13, and integrations/gh-aw/AGENTS.md lines 22-26. Keep the existing
installation paths and subsequent setup steps unchanged while ensuring all
documented and CI installations use the same pinned version.
| ### GitHub Agentic Workflows (gh-aw) | ||
|
|
||
| Only relevant when changing `integrations/gh-aw/`. All of these were confirmed | ||
| against gh-aw v0.83.4 by compiling, not by reading documentation. |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Locate docs/GOTCHAS.md and AGENTS.md"
git ls-files | rg '(^|/)(GOTCHAS\.md|AGENTS\.md)$' || true
echo
echo "Relevant GOTCHAS section:"
if [ -f docs/GOTCHAS.md ]; then
nl -ba docs/GOTCHAS.md | sed -n '130,190p'
fi
echo
echo "Search gh-aw references:"
rg -n "gh-aw|gh aw|Agentic Workflows|real run|runtime|compile|compiled" docs AGENTS.md integrations 2>/dev/null | head -200 || trueRepository: matthiasbigl/err2issue
Length of output: 362
🌐 Web query:
GitHub Agentic Workflows gh aw compile validation does not execute docs
💡 Result:
The GitHub Agentic Workflows (gh-aw) CLI provides two primary commands for validating workflows: gh aw compile --validate and the dedicated gh aw validate command [1][2]. If you are experiencing issues where validation does not appear to execute as expected, consider the following points based on official documentation and command behavior: 1. Use the Dedicated Validation Command: The gh aw validate command was introduced as an ergonomic entry point that specifically runs compilation combined with all linting and security checkers (zizmor, actionlint, and poutine) without emitting lock files [1][2][3]. It is functionally equivalent to running gh aw compile --validate --no-emit --zizmor --actionlint --poutine [1][3]. 2. Understanding gh aw compile --validate: When using gh aw compile, the --validate flag instructs the compiler to validate the workflow without generating output files (equivalent to --no-emit) [4][1][5]. If this command is not running expected checks, ensure that: - You are not accidentally overriding the behavior with other flags. - The repository is correctly initialized with gh aw init, as certain validations (such as manifest validation) rely on a proper aw.yml setup in the repository root [1][6]. 3. Always-On Defaults: Note that for the gh aw validate command, linters like zizmor, actionlint, and poutine are "always-on" defaults and cannot be disabled [1]. If you are not seeing output from these tools, verify that they are installed and accessible to the gh-aw extension. 4. Verbose Mode: If you suspect validation is silently failing or skipping checks, run the command with the --verbose flag to inspect the compilation phases and identify if specific validation steps (parsing, schema validation, or security scanning) are being bypassed [4][7]. If the issue persists, ensure your gh-aw extension is updated to the latest version by running gh extension upgrade aw [8].
Citations:
- 1: https://github.github.com/gh-aw/setup/cli/
- 2: feat: add
gh aw validatecommand github/gh-aw#18191 - 3: [docs] Update documentation for features from 2026-02-25 github/gh-aw#18254
- 4: https://github.github.com/gh-aw/reference/compilation-process/
- 5: https://github.com/github/gh-aw/blob/main/.github/aw/cli-commands.md
- 6: https://github.github.com/gh-aw/specs/repository-package-manifest-specification/
- 7: feat: add validate operation to agentic maintenance workflow github/gh-aw#25889
- 8: https://github.com/github/gh-aw/blob/main/create.md
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Relevant GOTCHAS section:"
sed -n '130,190p' docs/GOTCHAS.md
echo
echo "Relevant AGENTS.md gh-aw sections:"
sed -n '1,220p' integrations/gh-aw/AGENTS.md 2>/dev/null || true
echo
echo "Search gh-aw runtime vs compile wording:"
rg -n "gh-aw|gh aw|Agentic Workflows|real run|runtime|compile|compiled|verify|running|run" docs AGENTS.md integrations/gh-aw 2>/dev/null || trueRepository: matthiasbigl/err2issue
Length of output: 30164
Distinguish compile-only claims from runtime behavior.
gh aw compile validates frontmatter/schema, but several bullets are about runtime failure modes: CI triggering, billing/PAT fallback, Copilot inference permission, and prompt output. Replace “All of these were confirmed against gh-aw v0.83.4 by compiling” with wording that separates compiler-verified behavior from documented or runtime-dependent cases.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@docs/GOTCHAS.md` around lines 146 - 149, Update the introductory
qualification in the “GitHub Agentic Workflows (gh-aw)” section to distinguish
claims verified by gh aw compile from runtime behavior and documented behavior.
Do not imply that CI triggering, billing/PAT fallback, Copilot inference
permissions, or prompt output were confirmed by compilation; preserve the gh-aw
v0.83.4 version context.
Source: Learnings
| Put the parts you never want a team to weaken into `shared/err2issue-safety.md`: | ||
|
|
||
| ```yaml | ||
| --- | ||
| permissions: | ||
| contents: read | ||
| issues: read | ||
| pull-requests: read | ||
| copilot-requests: write | ||
|
|
||
| max-ai-credits: 300 | ||
| max-daily-ai-credits: 2000 | ||
|
|
||
| safe-outputs: | ||
| create-pull-request: | ||
| draft: true | ||
| add-comment: | ||
| max: 1 | ||
| --- | ||
| ``` | ||
|
|
||
| and import it from the workflow: | ||
|
|
||
| ```yaml | ||
| imports: | ||
| - acme/agentic-workflows/shared/err2issue-safety.md@v1 | ||
| ``` | ||
|
|
||
| `imports:` merges `permissions`, `safe-outputs`, `tools`, `network`, `env`, | ||
| `mcp-servers` and others from the imported file. Remote imports are cached | ||
| under `.github/aw/imports/` **by commit SHA**, and the compiled `.lock.yml` | ||
| records that SHA — so a compile is reproducible even though the source lives in | ||
| another repository. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate relevant files =="
git ls-files | rg '(^|/)gh-aw/(ORGANIZATIONS|references|reference).*|imports|\.github/aw|shared/err2issue-safety\.md|lock\.yml|workflows|permissions|safe-outputs' || true
echo
echo "== inspect ORGANIZATIONS section =="
if [ -f integrations/gh-aw/ORGANIZATIONS.md ]; then
nl -ba integrations/gh-aw/ORGANIZATIONS.md | sed -n '1,140p'
fi
echo
echo "== search for gh-aw docs related to imports validation/merge behavior =="
rg -n "imports|gh-aw|acme/agentic-workflows|permissions|safe-outputs|compiled|\.lock\.yml|commit SHA|overrides|unoverrideable|w(eak|ith)" -S . --glob '!vendor/**' --glob '!dist/**' --glob '!node_modules/**' || true
echo
echo "== search repository docs for gh-aw official reference URLs =="
rg -n "github\.github\.com/gh-aw|github\.com/actions/workflows|gh-aw/reference|reference/imports" -S . || trueRepository: matthiasbigl/err2issue
Length of output: 504
🌐 Web query:
gh-aw reference imports valid permission subset main workflow permissions compiled lock SHA safe-outputs
💡 Result:
In GitHub Agentic Workflows (gh-aw), the terms mentioned relate to a security-first architecture designed to maintain least-privilege for agentic jobs while enabling controlled write operations. Permissions and Imports The gh-aw system uses a strict validation model for permissions [1][2]. When workflows import shared components, permissions are not merged; instead, the main workflow must explicitly declare all required permissions, and the system validates that these main-level permissions are sufficient to satisfy the requirements of any imported shared workflows [1][2]. If permissions are missing or insufficient, the workflow will fail compilation [2]. All permissions in the permissions: block must be declared as read [3]. The only exception is copilot-requests: write, which is used to enable Copilot inference using the built-in GitHub Actions token [3][4]. Safe-Outputs To maintain security, the main agentic job is kept read-only [5][6]. Any GitHub write operations must be routed through the safe-outputs: mechanism [5][7]. This separates the agent (which runs with read-only access) from the actual execution of write actions, which are performed by a separate, permission-controlled safe-outputs job [7]. Safe-Outputs Runtime and ID Tokens The safe-outputs job automatically detects known OIDC or vault-related actions in safe-outputs.steps and will configure id-token: write permissions automatically [8][9]. Users can override this behavior using the safe-outputs.id-token field, setting it to write (to force enable) or none (to suppress) [8][9]. Lock SHA and Compilation The system relies on compilation-time resolution for security [2][8]. Actions and dependencies are resolved at compile time, and the compiler ensures that the workflow is safe to execute [2][8]. While a "lock SHA" was mentioned in your query, in the context of gh-aw, this refers to the compiler-driven resolution of workflow components (such as actions or shared workflows) to specific references (tags, SHAs, or branches) to ensure immutable and predictable execution [8]. Summary of Key Constraints: - Main agent jobs must remain read-only [5][6]. - All permissions must be declared explicitly in the main workflow [2]. - Permissions are validated, not merged, across imports [1]. - Writes must be performed via safe-outputs: [7]. - OIDC/Vault authentication in safe-outputs is auto-detected and managed [9].
Citations:
- 1: https://github.github.com/gh-aw/reference/imports/
- 2: Add permissions support to shared workflows with validation (explicit declaration required) github/gh-aw#2781
- 3: https://github.github.com/gh-aw/reference/permissions/
- 4: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/auth.mdx
- 5: https://github.com/githubnext/gh-aw/blob/main/.github/aw/github-agentic-workflows.md
- 6: https://github.com/github/gh-aw/blob/main/.github/aw/workflow-constraints.md
- 7: https://github.github.com/gh-aw/reference/safe-outputs/
- 8: https://github.com/github/gh-aw/blob/main/.github/aw/safe-outputs-runtime.md
- 9: Auto-detect OIDC/vault actions in safe-outputs steps and add id-token:write permission github/gh-aw#18701
🌐 Web query:
"gitsafe://" "github.github.com/gh-aw/reference/imports" "permissions are not merged"
💡 Result:
There is no recognized "gitsafe://" protocol in standard Git or GitHub infrastructure. The term "gitsafe" appears in unrelated contexts, such as a third-party repository archival tool [1] or as an internal remote name used by platforms like Replit for disaster recovery [2]. Regarding "github.github.com/gh-aw/reference/imports", this refers to the documentation for GitHub Agentic Workflows (gh-aw) [3]. The "imports" feature allows users to share and reuse workflow components across different repositories or files [3]. If you are experiencing issues where permissions or configurations are "not merged," this is likely related to the Safe Settings application—a separate tool often used to manage GitHub organization settings via policy-as-code [4][5]. Users frequently report that Safe Settings may override or fail to merge permissions as expected if the configuration is not structured correctly [4][6]. Key troubleshooting points for configuration merging: 1. Safe Settings Hierarchies: Ensure that your settings.yml is correctly defined across the organization, sub-organization, and repository levels [7]. Repo-level settings take the highest precedence and will override higher-level configurations [7]. 2. Merging vs. Replacing: In Safe Settings, explicitly defining teams or collaborators can sometimes overwrite existing ones if not configured to perform an additive merge [4][7]. Review your settings.yml to ensure you are not inadvertently replacing entire lists [4]. 3. Permission Roles: Ensure you are using supported roles (e.g., admin, push, pull), as some newer or custom roles may not be fully supported by all versions of the Safe Settings application, leading to unnecessary re-applications or failures [6][8]. If you are encountering a specific error message involving an "imports" path in GitHub Agentic Workflows, verify that your path format follows the supported patterns: relative paths (starting with shared/ or ../), repo-root-relative paths (starting with .github/ or /), or cross-repo imports (using the owner/repo/path@ref format) [9][10][11].
Citations:
- 1: https://github.com/j0rsa/gitsafe
- 2: https://docs.replit.com/features/version-control/disaster-recovery
- 3: https://github.github.com/gh-aw/reference/imports/
- 4: SafeSettings removes existing team permission for all the repos github-community-projects/safe-settings#350
- 5: https://github.com/github/safe-settings/blob/b86aa10a6e2c342a86db32fdbe69b62b55fe9d51/README.md
- 6: Safe-settings reapplies collaborator maintain permissions github-community-projects/safe-settings#636
- 7: https://github-safe-settings.mintlify.app/configuration/repo-settings
- 8: https://github-safe-settings.mintlify.app/settings/collaborators
- 9: docs: document import path resolution modes (relative, repo-root-relative, cross-repo) github/gh-aw#24536
- 10: https://github.com/github/gh-aw/blob/main/.github/aw/reuse.md
- 11: Add minimal path format syntax reference to imports documentation github/gh-aw#2097
🌐 Web query:
"Safe-Outputs" "id-token" "gh-aw reference safe-outputs"
💡 Result:
In the context of the GitHub Agentic Workflows (gh-aw) project, the id-token field within the safe-outputs configuration is used to manage OIDC permissions for the consolidated safe-outputs job [1]. The id-token field accepts either "write" or "none" as a string value [1]: - "write": Forces the enablement of id-token: write permissions, which is necessary for OpenID Connect (OIDC) authentication with cloud providers (e.g., AWS, Azure, Google Cloud) [1][2]. - "none": Suppresses automatic detection and prevents the addition of id-token: write even if OIDC or vault-related actions are detected in the job's steps [1]. By default, the system automatically detects known OIDC or vault-related actions (such as aws-actions/configure-aws-credentials, hashicorp/vault-action, or azure/login) and adds id-token: write permissions automatically [1][3]. The id-token configuration allows you to override this automatic behavior when necessary [1].
Citations:
- 1: https://github.com/github/gh-aw/blob/main/.github/aw/safe-outputs-runtime.md
- 2: docs: Document GitHub App token implementation and clarify OIDC distinction github/gh-aw#11656
- 3: Safe Output custom token source github/gh-aw#18362
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== read ORGANIZATIONS relevant section =="
awk 'NR>=1 && NR<=150 {printf "%6d\t%s\n", NR, $0}' integrations/gh-aw/ORGANIZATIONS.md
echo
echo "== read workflow example around imports if present =="
if [ -f integrations/gh-aw/workflows/err2issue-autofix.md ]; then
awk 'NR>=1 && NR<=220 {printf "%6d\t%s\n", NR, $0}' integrations/gh-aw/workflows/err2issue-autofix.md
fi
echo
echo "== search precise gh-aw import semantics in repo docs =="
awk 'NR>=1 && NR<=220 {print NR"\t"$0}' README.md 2>/dev/null || trueRepository: matthiasbigl/err2issue
Length of output: 26239
Clarify imports as validated policy, not unoverrideable guarantees.
gh-aw validates that the main workflow has sufficient permissions rather than merging imported permissions into the workflow, and local values can override imported configuration. Reword lines 89-93 to avoid implying that importing err2issue-safety.md makes the shared permissions, safe-outputs, caps, or other fields unchangeable by main workflow fields.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~91-~91: The official name of this software platform is spelled with a capital “H”.
Context: ...d file. Remote imports are cached under .github/aw/imports/ by commit SHA, and the...
(GITHUB)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/gh-aw/ORGANIZATIONS.md` around lines 61 - 93, Revise the imports
explanation after the err2issue-safety.md example to describe imported settings
as validated policy defaults rather than unoverrideable guarantees. State that
gh-aw validates required permissions, while main-workflow values can override
imported permissions, safe-outputs, caps, and other supported fields; retain the
commit-SHA caching and lockfile reproducibility details.
| ## 4. Cost, at org scale | ||
|
|
||
| This is where an org deployment differs most from one repository, because the | ||
| failure mode is not "it broke" but "it quietly cost a lot". | ||
|
|
||
| - **Billing is to the org, not to a person.** That is the point of | ||
| `copilot-requests: write` — but note the consequence GitHub states plainly: | ||
| *user-level inference budgets are not considered when billing directly to the | ||
| organization, because the cost is not attributed to a user.* The per-user | ||
| guardrail you may be relying on does not apply. `max-ai-credits` and | ||
| `max-daily-ai-credits` in the shared import are what replaces it. | ||
| - **Set defaults centrally.** `GH_AW_DEFAULT_MAX_AI_CREDITS`, | ||
| `GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS` and `GH_AW_DEFAULT_TIMEOUT_MINUTES` are | ||
| read as GitHub Actions variables, so an org-level variable sets the floor for | ||
| every workflow without editing any of them. `gh aw env` manages these. | ||
| - **Look before you widen.** `gh aw logs` and `gh aw audit` show which runs | ||
| consumed the most time and credits; `gh aw forecast` projects usage from | ||
| history. Tighten the prompt and the trigger before raising a cap. | ||
| - **err2issue's own throttles are upstream of all of this.** | ||
| `E2I_MAX_NEW_FINGERPRINTS_PER_DAY` (default 50) bounds how many issues can be | ||
| filed in a day, and therefore how many agent runs a bad deploy can trigger. If | ||
| you are worried about agent spend, that setting is a cheaper lever than | ||
| anything in gh-aw, because it prevents the run rather than capping it. |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== repo files =="
git ls-files | rg '(^|/)integrations/gh-aw/(ORGANIZATIONS.md|.*\.md)$|gh-aw' | head -200
echo
echo "== target file excerpt =="
sed -n '1,220p' integrations/gh-aw/ORGANIZATIONS.md
echo
echo "== mentions of relevant symbols =="
rg -n "GH_AW_DEFAULT_MAX_AI_CREDITS|GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS|GH_AW_DEFAULT_TIMEOUT_MINUTES|gh aw env|Actions variables|runtime|compiler-process|GitHub Actions" integrations/gh-aw -S || trueRepository: matthiasbigl/err2issue
Length of output: 8862
🌐 Web query:
gh-aw reference GH_AW_DEFAULT_MAX_AI_CREDITS GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS GitHub Actions variables compiler-process variables
💡 Result:
GH_AW_DEFAULT_MAX_AI_CREDITS and GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS are environment variables used in GitHub Agentic Workflows (gh-aw) to govern AI credit consumption for workflows [1][2]. They are configured as GitHub Actions variables (vars.*) and are resolved at runtime, not at compile time [1][3]. Purpose and Functionality: - GH_AW_DEFAULT_MAX_AI_CREDITS: Sets the default per-run AI credit budget [1]. If not specified in workflow frontmatter or imported shared workflows, the system defaults to 1,000 AI Credits (AIC) [1][3]. - GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS: Sets the default guardrail for total AI credits a workflow can consume in a rolling 24-hour window [1][4]. If not configured, the built-in default is 5,000 AIC [1][3]. Resolution Precedence: For both variables, the system follows a strict hierarchy [1][3]: 1. Workflow frontmatter (compile-time literal) [1][3]. 2. Imported shared workflows (compile-time, "first-wins") [1][3]. 3. GitHub Actions variable (vars.GH_AW_DEFAULT_...) (resolved at runtime) [1][3]. 4. Built-in constant default (1,000 for per-run; 5,000 for daily) [1][3]. Implementation Details: - Compiler Behavior: Conforming compilers must not read these variables at compile time [3]. Instead, they must emit a GitHub Actions expression—specifically ${{ vars.GH_AW_DEFAULT_MAX_AI_CREDITS || '1000' }} and ${{ vars.GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS || '5000' }}—into the compiled YAML so the runner resolves the value dynamically [1][3]. - Management: These variables can be managed via the gh aw env CLI tool, which maps YAML configuration keys (e.g., default_max_ai_credits) to the corresponding GitHub Actions variables [5][2]. - Value Formatting: Both variables support positive integers and can accept K/M suffixes (e.g., '100M') [1][2]. A value of -1 disables the respective guardrail [1][2]. Note on Compiler-Process Variables: While the variables are resolved at runtime by the runner, when compiling workflows in a CI/CD environment, you may need to pass compiler-read defaults into the process environment using ${{ vars.* }} expressions to ensure the compiler process has access to your organization's configured defaults during the compilation step [5][2].
Citations:
- 1: https://github.github.com/gh-aw/reference/compiler-enterprise-environment-controls/
- 2: https://github.github.com/gh-aw/reference/cost-management/
- 3: https://github.github.com/gh-aw/specs/ai-credits-specification/
- 4: https://github.github.com/gh-aw/reference/rate-limiting-controls/
- 5: https://github.github.com/gh-aw/guides/governance/
🌐 Web query:
gh aw env gh-aw environment variables gh aw env GH_AW_DEFAULT_TIMEOUT_MINUTES
💡 Result:
GH_AW_DEFAULT_TIMEOUT_MINUTES is an environment variable used by the gh aw CLI tool to set a default execution timeout for agentic workflows when a specific timeout is not defined in the workflow's frontmatter [1][2]. When compiling or running workflows, the system evaluates the timeout limit based on the following precedence [1]: 1. The timeout-minutes value explicitly set in the workflow frontmatter. 2. The GH_AW_DEFAULT_TIMEOUT_MINUTES environment variable. 3. The built-in compiler default. You can configure this variable in your local shell environment, as a repository or organization variable in GitHub Actions, or manage it via the gh aw CLI [3][1][4]. For instance, you can export it in your shell before running compilation steps: export GH_AW_DEFAULT_TIMEOUT_MINUTES=30 Additionally, the gh aw CLI provides commands such as gh aw env update (or the newer gh aw defaults update) to manage these enterprise-level environment controls across different scopes (repository, organization, or enterprise) [1][2]. Setting this variable ensures that your workflows have a governed execution boundary even when individual authors omit configuration [2].
Citations:
- 1: https://github.github.com/gh-aw/reference/compiler-enterprise-environment-controls/
- 2: Centralize compiler enterprise env controls, expand GH_AW_DEFAULT_* overrides, and add
gh aw defaultsbatch management github/gh-aw#35286 - 3: https://github.github.com/gh-aw/reference/environment-variables/
- 4: https://github.github.com/gh-aw/reference/cost-management/
Correct the organization-defaults contract.
GH_AW_DEFAULT_MAX_AI_CREDITS and GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS are downstream runtime precedence for gh-aw defaults; they can be overridden by compiled workflow/imported values, so they are not floors. GH_AW_DEFAULT_TIMEOUT_MINUTES is a compiler-process variable, so gh aw env alone does not apply it unless the compile job passes it into the compiler environment.
🧰 Tools
🪛 LanguageTool
[uncategorized] ~152-~152: Do not mix variants of the same word (‘organization’ and ‘organisation’) within a single text.
Context: ...nsidered when billing directly to the organization, because the cost is not attributed to ...
(EN_WORD_COHERENCY)
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/gh-aw/ORGANIZATIONS.md` around lines 144 - 166, Correct the “Set
defaults centrally” section to describe GH_AW_DEFAULT_MAX_AI_CREDITS and
GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS as downstream gh-aw runtime defaults that may
be overridden by compiled or imported workflow values, not organization-wide
floors. Clarify that GH_AW_DEFAULT_TIMEOUT_MINUTES is read by the compiler
process and only applies when the compile job passes it into the compiler
environment; update the gh aw env guidance accordingly.
| ## 6. Roll out in the order that lets you stop | ||
|
|
||
| 1. **Staged.** `safe-outputs: { staged: true }` runs the agent and writes a step | ||
| summary of what it *would* have done, making no API calls at all. One | ||
| repository, a week, no consequences. | ||
| 2. **Comment-only.** Drop `create-pull-request`, keep `add-comment`. Now you are | ||
| reading real analysis on real errors and can judge whether the issue contract | ||
| carries enough context on *your* codebase. | ||
| 3. **Draft pull requests, one repository.** The shipped configuration. | ||
| 4. **Widen the repository set**, not the permissions. | ||
|
|
||
| `gh aw trial` runs a workflow against a simulated repository if you want step 0. | ||
|
|
||
| At every stage the safety property is the same: **what is not declared in | ||
| `safe-outputs` cannot happen**, regardless of what the agent decides. That is | ||
| the reason to use gh-aw for this rather than a plain Actions workflow, and it is | ||
| worth not undermining by widening the block to make a single run succeed. |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "Repository files around ORGANIZATIONS.md:"
fd -a 'ORGANIZATIONS\.md$|safe-outputs|staged_mode|staged' . | sed 's#^\./##' | head -100
echo
echo "Target excerpt:"
if [ -f integrations/gh-aw/ORGANIZATIONS.md ]; then
cat -n integrations/gh-aw/ORGANIZATIONS.md | sed -n '170,220p'
fi
echo
echo "Search staged/safe-output references:"
rg -n --smart-case "staged|safe-outputs|safe outputs|no API|API calls|no permanent|permanent|create-pull-request|add-comment|gh aw trial" . | sed -n '1,200p'Repository: matthiasbigl/err2issue
Length of output: 7376
🌐 Web query:
GitHub gh-aw reference staged-mode safe-outputs staged true
💡 Result:
In GitHub Agentic Workflows (gh-aw), Staged Mode is a preview execution feature that allows you to simulate workflow actions without creating permanent resources on GitHub [1][2]. When Staged Mode is enabled, the agent evaluates the workflow and generates a preview of its intended actions (such as creating issues, comments, or pull requests) in the GitHub Actions step summary instead of performing the actual API calls [1][2]. Configuration You can enable Staged Mode by adding staged: true to the safe-outputs section of your workflow configuration [1][3]. Global vs. Type-Specific Configuration - Global: Setting staged: true under safe-outputs applies this mode to all safe output types in the workflow [1][2]. - Type-Specific: You can override the global setting for individual output types (e.g., create-pull-request) by specifying staged: true or false directly under that specific output type [1][2]. Implementation Details - Environment Variable: When Staged Mode is active, custom jobs or safe output implementations receive the environment variable GH_AW_SAFE_OUTPUTS_STAGED set to "true" [1]. This allows custom logic to detect the mode and implement appropriate preview behaviors (e.g., skipping a Slack notification and printing the message in the summary instead) [1]. - Conformance: Implementations are required to skip all GitHub API write operations when in Staged Mode, ensure consistent emoji-prefixed messaging, and provide sufficient detail in the preview summaries to allow for accurate evaluation [2]. Note: As of March 2026, there have been reports of issues where type-specific staged: true overrides may not behave as expected in certain contexts within safe outputs [4].
Citations:
- 1: https://github.github.com/gh-aw/reference/staged-mode/
- 2: https://github.github.com/gh-aw/specs/safe-outputs-specification/
- 3: https://github.github.com/gh-aw/reference/safe-outputs/
- 4: Option
staged: truedoes not work within individual safe outputs github/gh-aw#22409
Use the staged-mode wording from the spec.
safe-outputs: { staged: true } skips safe-output write operations rather than skipping all API calls. Say it writes a step summary of intended actions without creating permanent GitHub resources.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/gh-aw/ORGANIZATIONS.md` around lines 192 - 208, Update the
“Staged” description in the rollout section to state that safe-output write
operations are skipped, not all API calls. Preserve that it writes a step
summary of intended actions and clarify that it does not create permanent GitHub
resources.
| ### Cost ceilings | ||
|
|
||
| ```yaml | ||
| engine: claude | ||
| max-ai-credits: 300 # per run | ||
| max-daily-ai-credits: 2000 # rolling 24 hours, per user per workflow | ||
| ``` |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== locate file =="
git ls-files | rg '(^|/)integrations/gh-aw/README\.md$|gh-aw' || true
echo "== README relevant lines =="
if [ -f integrations/gh-aw/README.md ]; then
nl -ba integrations/gh-aw/README.md | sed -n '100,145p'
fi
echo "== search for cost cap references =="
rg -n "max-daily-ai-credits|max-ai-credits|daily.*credits|credit|cost" . --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' | head -n 200Repository: matthiasbigl/err2issue
Length of output: 390
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== README relevant lines =="
awk 'NR>=100 && NR<=150 { printf "%6d\t%s\n", NR, $0 }' integrations/gh-aw/README.md
echo "== search cost cap references in gh-aw =="
awk 'NR>=1 && NR<=500 { printf "%6d\t%s\n", NR, $0 }' integrations/gh-aw/README.md integrations/gh-aw/AGENTS.md integrations/gh-aw/ORGANIZATIONS.md integrations/gh-aw/workflows/err2issue-autofix.md | rg -n "max-daily-ai-credits|max-ai-credits|daily.*credits|credit|cost" || true
echo "== repository references to max-daily-ai-credits =="
rg -n "max-daily-ai-credits|max-ai-credits" . --glob '!node_modules/**' --glob '!dist/**' --glob '!build/**' || trueRepository: matthiasbigl/err2issue
Length of output: 4175
🌐 Web query:
GitHub reference cost-management gh-aw max-daily-ai-credits per-user per workflow
💡 Result:
In the context of GitHub Agentic Workflows (gh-aw), the max-daily-ai-credits setting is a repository and workflow-scoped guardrail, not a per-user limit [1][2]. Key details regarding this guardrail include: Scope: The guardrail aggregates AI Credit (AIC) consumption across all completed runs of a specific workflow within a repository over a rolling 24-hour window, regardless of the individual who triggered those runs [3][1][2]. It is important not to confuse this with per-user rate limits [1][4]. Functionality: - Configuration: You can set the cap using the max-daily-ai-credits frontmatter field in your workflow YAML file [3][5]. It accepts integers or K/M suffixes (e.g., 100K, 15M) [3][6]. - Default Behavior: If omitted, the guardrail defaults to a system-defined threshold (currently 5,000 AIC) unless overridden by the GH_AW_DEFAULT_MAX_DAILY_AI_CREDITS enterprise or organization-level environment variable [7][4][5]. - Disabling: Setting the value to -1 in the frontmatter or environment variable disables the daily guardrail for that scope [3][2][5]. - Bypassing: The daily guardrail is automatically bypassed for intentional user-initiated actions, including manual workflow_dispatch triggers, slash commands, label commands, and centralized invocations like workflow_call or repository_dispatch events [4]. When the aggregated consumption of a workflow exceeds the configured threshold, the activation job reports the failure and skips the agent job for subsequent runs until the 24-hour window resets [3][2]. Note: This guardrail is distinct from personal GitHub Copilot usage limits (such as session or weekly limits) or organizational billing budgets [1][8][9]. While the agentic guardrail manages workflow-specific spending, personal Copilot limits are based on individual plan entitlements and overall token consumption [8][10].
Citations:
- 1: fix: scope daily AIC guardrail to repo+workflow, not per user github/gh-aw#37634
- 2: [aw] Test Quality Sentinel exceeded daily AI credits budget github/gh-aw#39059
- 3: https://github.github.com/gh-aw/reference/cost-management/
- 4: https://github.github.com/gh-aw/reference/rate-limiting-controls/
- 5: https://github.github.com/gh-aw/specs/ai-credits-specification/
- 6: https://github.com/github/gh-aw/blob/main/.github/aw/token-optimization.md
- 7: Add
max-daily-ai-creditsfrontmatter guardrail and deprecatemax-daily-effective-tokensgithub/gh-aw#37101 - 8: https://github.blog/news-insights/company-news/changes-to-github-copilot-individual-plans/
- 9: https://docs.github.com/en/copilot/concepts/agents/copilot-cli/copilot-cli-in-github-actions
- 10: https://docs.github.com/en/copilot/concepts/billing/usage-based-billing-for-individuals
Describe max-daily-ai-credits as a workflow-wide cap.
This setting aggregates the workflow’s completed runs over the rolling 24-hour window, not one user’s spend. Update the per user per workflow comment to avoid underselling the shared credit boundary.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/gh-aw/README.md` around lines 120 - 125, Update the
max-daily-ai-credits documentation comment in the Cost ceilings example to
describe it as a workflow-wide cap aggregating completed runs over the rolling
24-hour window, and remove the misleading per-user qualification.
| # Bills Copilot inference to the organisation through the built-in | ||
| # GITHUB_TOKEN, so no COPILOT_GITHUB_TOKEN PAT is needed. Requires the org | ||
| # policy "Allow use of Copilot CLI billed to the organization". Without both, | ||
| # the run falls back to per-seat billing and needs that PAT — see README. | ||
| copilot-requests: write |
There was a problem hiding this comment.
🔒 Security & Privacy | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
gh-aw reference auth copilot-requests COPILOT_GITHUB_TOKEN organization billing fallback
💡 Result:
In GitHub Agentic Workflows (gh-aw), authentication for Copilot inference is handled via one of two primary methods, with a recommended approach based on centralized organization billing [1][2]. Recommended Method: copilot-requests: write The recommended way to authenticate Copilot inference is to grant the copilot-requests: write permission in your GitHub Actions workflow [1][3]. - How it works: This uses the built-in GitHub Actions token (${{ github.token }}), meaning no personal access token (PAT) or repository secret is required [1][2]. - Billing: Billing is handled centrally through your organization’s Copilot subscription [1][2]. - Priority: When this permission is present, the gh-aw engine automatically uses the GitHub Actions token, and any value set for COPILOT_GITHUB_TOKEN is ignored for inference [1][2]. Fallback Method: COPILOT_GITHUB_TOKEN When centralized organization billing is not available or you are working in personal repositories, you must use the COPILOT_GITHUB_TOKEN secret [1][2]. - Requirements: This must be a fine-grained PAT with the "Copilot Requests" permission [1][4]. - Constraints: The token's resource owner must be a personal account, not an organization [5][4]. - Behavior: If the necessary permissions are not found or configured for the organization-based approach, the system relies on this secret [1][6]. There is no further fallback to the default GITHUB_TOKEN for Copilot inference because it lacks the required Copilot Requests permission [5][4]. Migration Note Recent updates have removed the legacy features.copilot-requests feature flag. The enablement of "token mode" is now exclusively gated by the explicit workflow permission permissions.copilot-requests: write [7]. You can use the gh aw fix command to automatically migrate older configurations [7].
Citations:
- 1: https://github.github.com/gh-aw/reference/auth/
- 2: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/auth.mdx
- 3: docs: recommend
copilot-requests: writefor Copilot authentication github/gh-aw#38404 - 4: https://github.com/githubnext/gh-aw/blob/main/docs/src/content/docs/reference/tokens.md
- 5: https://github.github.com/gh-aw/reference/tokens/
- 6: Fix secret validation false warnings for copilot org billing mode github/gh-aw#38459
- 7: Remove
features.copilot-requests; gate Copilot token mode onpermissions.copilot-requests: write, add migration codemod, and apply migration across repo workflows github/gh-aw#35642
🌐 Web query:
gh-aw reference auth copilot-requests write organization billing organization billing denied COPILOT_GITHUB_TOKEN
💡 Result:
When using GitHub Agentic Workflows (gh-aw), you can authenticate Copilot inference using either the recommended copilot-requests: write permission or a COPILOT_GITHUB_TOKEN [1][2][3]. If you are encountering an "organization billing denied" or 403 authorization error while using permissions: copilot-requests: write, it indicates that your workflow is configured to bill Copilot usage to your organization, but the necessary prerequisites are not met [1][4][2]. To resolve this: 1. Enable Centralized Billing: Ensure your organization has enabled the policy "Allow use of Copilot CLI billed to the organization" in your Organization Settings under Copilot → Policies [5][6]. 2. Verify Permissions: Confirm that your workflow's frontmatter explicitly includes the copilot-requests: write permission [2][5][6]. yaml permissions: contents: read copilot-requests: write 3. Understand Token Precedence: When copilot-requests: write is present in your workflow, the system automatically uses the GitHub Actions token for inference [2][3]. Any COPILOT_GITHUB_TOKEN or GH_AW_GITHUB_TOKEN environment variables set in the workflow are ignored for inference purposes [1][2]. If centralized billing is not available or you choose not to use it, you must remove the copilot-requests: write permission from your workflow and instead provide a valid COPILOT_GITHUB_TOKEN (a fine-grained personal access token with "Copilot Requests" permission) as an environment variable [1][2][5]. In this case, Copilot usage will be billed to the individual account that owns the PAT rather than the organization [2][5].
Citations:
- 1: https://github.com/github/gh-aw/blob/main/docs/src/content/docs/reference/auth.mdx
- 2: https://github.github.com/gh-aw/reference/auth/
- 3: docs: recommend
copilot-requests: writefor Copilot authentication github/gh-aw#38404 - 4: Improve Copilot 403 auth guidance for copilot-requests mode github/gh-aw#40052
- 5: https://github.github.com/gh-aw/reference/billing/
- 6: https://docs.github.com/en/copilot/how-tos/github-agentic-workflows/creating-github-agentic-workflows
🏁 Script executed:
#!/bin/bash
set -euo pipefail
printf 'Relevant workflow excerpt:\n'
sed -n '28,43p;180,196p' integrations/gh-aw/workflows/err2issue-autofix.md || true
printf '\nRelevant README excerpts:\n'
sed -n '96,122p;178,195p' integrations/gh-aw/README.md || trueRepository: matthiasbigl/err2issue
Length of output: 3655
Align the Copilot authentication contract across the workflow and documentation.
With permissions: copilot-requests: write, gh-aw uses the workflow GITHUB_TOKEN for Copilot inference and ignores COPILOT_GITHUB_TOKEN; unavailable organization billing does not automatically fall back to the PAT configuration. Document org-billing and PAT-mode as separate configurations, including removing copilot-requests: write for PAT mode.
integrations/gh-aw/workflows/err2issue-autofix.md#L35-L39: replace “falls back to per-seat billing and needs that PAT” with separate org-billing vs. PAT workflow configuration guidance.integrations/gh-aw/README.md#L106-L118: remove the automatic fallback claim and clarify separate configuration for personal/PAT scenarios.
📍 Affects 2 files
integrations/gh-aw/workflows/err2issue-autofix.md#L35-L39(this comment)integrations/gh-aw/README.md#L106-L118
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/gh-aw/workflows/err2issue-autofix.md` around lines 35 - 39,
Align the Copilot authentication documentation across both affected sites: in
integrations/gh-aw/workflows/err2issue-autofix.md lines 35-39, replace the
automatic per-seat fallback claim with distinct org-billing guidance using
copilot-requests: write and PAT-mode guidance that removes that permission and
configures COPILOT_GITHUB_TOKEN; in integrations/gh-aw/README.md lines 106-118,
remove the automatic fallback claim and document personal/PAT usage as a
separate workflow configuration.
| # A pull request opened with the built-in GITHUB_TOKEN does not start CI — | ||
| # GitHub blocks that to prevent workflow recursion. Setting a repository | ||
| # secret named GH_AW_CI_TRIGGER_TOKEN (a fine-grained PAT with | ||
| # Contents: Read & Write) is picked up automatically; this line is the | ||
| # explicit form. Delete it if you set the magic secret name instead, or if | ||
| # you are happy reviewing agent PRs with no checks. See README. | ||
| github-token-for-extra-empty-commit: ${{ secrets.GH_AW_CI_TRIGGER_TOKEN }} |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
GitHub Actions GITHUB_TOKEN pull_request workflow triggered by pull request no CI checks
💡 Result:
If your GitHub Actions workflow is not running when a pull request is created or updated, it is likely due to GitHub's built-in recursive-execution protection or security restrictions regarding forked repositories [1][2][3]. Recursive Execution Protection: GitHub prevents workflows from triggering other workflows when they use the default GITHUB_TOKEN to perform actions (such as pushing code or opening a pull request) [1][2][3]. This is a security measure designed to prevent infinite loops [1][2][3]. - If an automated process (like a bot) creates or updates a pull request using the GITHUB_TOKEN, the resulting pull_request event does not trigger standard CI workflows automatically [1][4]. - Instead, these runs are created in an "approval-required" state [1][3]. A user with write access to the repository must manually approve the workflow run on the pull request page for it to execute [1][3]. - To bypass this and have workflows trigger automatically, you must use a Personal Access Token (PAT) or a GitHub App installation access token when creating or updating the pull request [1][2][4]. This allows GitHub to see the event as coming from a user or application rather than the automated GITHUB_TOKEN [4]. Forked Repository Restrictions: If the pull request originates from a forked repository, GitHub further restricts workflow execution to prevent abuse [5][6]. - By default, workflows triggered by pull requests from forks require manual approval from a maintainer with write access before they will run [7][6]. - You can manage this behavior in your repository settings under Settings > Actions > General > Workflow permissions [8][7]. Depending on your settings, this may only apply to first-time contributors or to all external contributors [7][6]. Other Common Causes: If the issue is not related to the GITHUB_TOKEN or fork restrictions, verify these common configuration issues: - Branch/Path Filters: Ensure that your workflow's on: pull_request: branches: or paths: filters match the pull request accurately [9][7]. Note that these filters are evaluated against the base branch (where the PR is merging), not the head branch [9]. - Workflow File Location: The workflow file must exist on the base branch of the repository for the trigger to be recognized [9][7]. - Syntax Errors: Ensure the YAML is valid; syntax errors can sometimes prevent a workflow from being parsed or triggered without explicit warnings in the Actions tab [7]. To resolve these issues, check the Actions tab in your repository; it will typically indicate if a run is "Waiting for approval" or if there is another configuration blocker [7][6].
Citations:
- 1: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow
- 2: Add FAQ entry: PRs from GitHub Actions bot don't trigger CI workflows github/gh-aw#15923
- 3: https://docs.github.com/en/actions/concepts/security/github_token
- 4: hookdeck/hookdeck-cli@65b64e4
- 5: https://docs.github.com/en/actions/reference/security/securely-using-pull_request_target
- 6: https://truffle.ghostwright.dev/public/blog/2026-06-26-fork-pr-zero-checks.html
- 7: https://devopsboys.com/blog/github-actions-workflow-not-triggering-fix-2026
- 8: https://stigcloud.com/2026/05/01/github-actions-workflow-not-triggering-fix-it-fast/
- 9: https://dev.to/opscanopy/why-your-github-actions-workflow-didnt-trigger-branches-tags-paths-filters-explained-1ib
🌐 Web query:
site:docs.github.com GITHUB_TOKEN GITHUB_TOKEN is not used to make pull_request events appear in Actions tab
💡 Result:
By design, GitHub Actions prevents the GITHUB_TOKEN from triggering new workflow runs to avoid infinite recursive loops [1][2]. Consequently, if a workflow uses the GITHUB_TOKEN to perform an action—such as creating or updating a pull request—that action will not trigger subsequent workflows configured to listen for those pull_request events, with specific exceptions [3][1][2]. The exceptions are as follows: 1. Approved Workflow Runs: If your workflow uses the GITHUB_TOKEN to open, synchronize, or reopen a pull request, the resulting pull_request event creates a workflow run that is placed in an approval-required state [3][1][2]. These runs will appear in the Actions tab, but they will not execute until a user with write access to the repository manually approves them from the pull request page [3][1][2]. 2. Other Activity Types: Pull request activity types other than opened, synchronize, or reopened (such as labeled, edited, or closed) do not create workflow runs at all when triggered by the GITHUB_TOKEN [3][1][2]. If you require workflows to trigger automatically without manual approval after being created or updated by automation, you must use a different authentication method, such as a personal access token (PAT) or a GitHub App installation access token, instead of the GITHUB_TOKEN [3][1][2].
Citations:
- 1: https://docs.github.com/en/enterprise-cloud@latest/actions/concepts/security/github_token
- 2: https://docs.github.com/en/actions/concepts/security/github_token
- 3: https://docs.github.com/en/actions/how-tos/write-workflows/choose-when-workflows-run/trigger-a-workflow
🏁 Script executed:
#!/bin/bash
set -e
printf 'Git diff stat:\n'
git diff --stat || true
printf '\nRelevant workflow/readme excerpts:\n'
if [ -f integrations/gh-aw/workflows/err2issue-autofix.md ]; then
sed -n '60,95p' integrations/gh-aw/workflows/err2issue-autofix.md
fi
printf '\n--- README ---\n'
if [ -f integrations/gh-aw/README.md ]; then
sed -n '170,205p' integrations/gh-aw/README.md
fiRepository: matthiasbigl/err2issue
Length of output: 2716
Avoid saying GITHUB_TOKEN never triggers pull_request workflows.
GitHub token-triggered pull-request events go to an approval-required state rather than executing automatically; workflows can still be created, so this docs wording differs from the intended “no checks run unless approved.” Use the PAT empty-commit path as the supported, non-approval-required CI trigger instead.
📍 Affects 2 files
integrations/gh-aw/workflows/err2issue-autofix.md#L77-L83(this comment)integrations/gh-aw/README.md#L187-L191
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@integrations/gh-aw/workflows/err2issue-autofix.md` around lines 77 - 83, The
documentation at integrations/gh-aw/workflows/err2issue-autofix.md:77-83 and
integrations/gh-aw/README.md:187-191 incorrectly says GITHUB_TOKEN prevents CI
workflows from starting. Update both references to explain that token-triggered
pull_request workflows require approval and do not run automatically, and
present the GH_AW_CI_TRIGGER_TOKEN PAT empty-commit path as the supported
non-approval-required CI trigger.
What and why
The gh-aw integration was written against documentation, with a "Verification
status" section admitting the workflow had never been compiled. I installed
gh-aw v0.83.4 and compiled it. Everything below is what the compiler said,
not what the docs imply.
The compiler is a real validator — unknown frontmatter keys, wrong value types,
and correct keys at the wrong nesting level all fail the build (
roles:at thetop level errors;
on.roles:compiles). So a clean compile is evidence ratherthan decoration.
Two real defects, both reported by the compiler on the first run:
Missing permission.
toolsets: [default]includes thepull_requeststoolset, which requires
pull-requests: read. Without it the workflowcompiled with a warning and would have failed at run time for anyone who
installed it.
The authentication claim was wrong. The file said
engine: copilot"needs no extra secret on GitHub-hosted runners." It did — inference was
billed per seat against a
COPILOT_GITHUB_TOKENPAT. The compiler emits thistip verbatim:
The PAT change, stated precisely
Since 11 June 2026,
permissions: copilot-requests: writebills Copilot inference to theorganisation through the built-in
GITHUB_TOKEN. The workflow now declares it.Two caveats the docs make easy to miss, and which this PR documents rather than
glosses:
GITHUB_TOKENdoes not triggerpull_requestorpushworkflows — GitHubblocks that to prevent recursion — so the agent's PR arrives with no CI
checks, which is the PR you least want unverified. That needs a separate
GH_AW_CI_TRIGGER_TOKENsecret (fine-grained PAT, Contents: Read & Write),which gh-aw picks up by name and uses to push one empty commit. Two tokens,
two problems; one of them is solved.
organization". On a personal repository, or an org without it, the run falls
back to per-seat billing and the
COPILOT_GITHUB_TOKENPAT.Also worth stating because it inverts a safety assumption: GitHub notes that
user-level inference budgets are not considered when billing directly to the
organization, because the cost is not attributed to a user. The per-user
guardrail stops applying exactly when you adopt this.
Approach
Every field added was probed individually against the compiler, with negative
controls to prove the compiler actually rejects things:
pull-requests: read+copilot-requests: write0 error(s), 0 warning(s)strict: true,max-ai-credits,max-daily-ai-credits,source:,description:on.roles: [...]github-token-for-extra-empty-commit:this-key-does-not-exist: truemax-ai-credits: "not-a-number"roles:at top level (wrong nesting)Confirmed in the generated
.lock.yml:copilot-requests: write,pull-requests: read,GH_AW_MAX_AI_CREDITS: "300", andGH_AW_CI_TRIGGER_TOKENin the manifest's secrets list.Beyond the two defects, the workflow gained
roles:(so an account with onlytriage access cannot spend AI credits by adding a label),
max-ai-credits: 300and
max-daily-ai-credits: 2000(gh-aw's default daily cap is 5000 AIC, ~$50),source:sogh aw updatecan 3-way merge future changes into installs, plusstrict:anddescription:.New
integrations/gh-aw/ORGANIZATIONS.mdcovers the part that does notscale by copying files: the central-repository pattern,
gh aw add/update/deploy, version pinning, a shared policy pulled in withimports:,the two admin prerequisites that fail confusingly (allowed-actions list,
Copilot CLI billing policy), GitHub App auth for cross-repo writes — including
that an App cannot authenticate Copilot inference — and a rollout order that
starts at
staged: trueand can be stopped at any step.integrations/gh-aw/AGENTS.mdhad a "valid top-level keys" list with nineentries. The real set is several times that and moves between releases, so the
rule is now to consult the reference and, more reliably, to ask the compiler.
Verification
Repository checks:
The new ORGANIZATIONS.md diagram was rendered with
mermaid-cliand inspected,per
docs/diagrams/README.md.The new CI gate was tested in all three directions, because a gate that
cannot fail is worthless:
Its first version was wrong: it grepped the log for
warning, which matches thesuccess line
0 error(s), 0 warning(s), so it would have failed every build.It now asserts that summary exactly. Caught by running it rather than reading it.
uv run pytestpassesuv run ruff check src tests scriptspasseschange; the CI gate is the check, exercised above
check_docs.pypasses and the new diagram was checked as arendered picture
Contract impact
src/err2issue/fingerprint.py)src/err2issue/context.py)src/is touched. This is the consumer side, whichreads the issue contract and does not define it.
Scope notes
not that the prompt produces a good fix. The AGENTS.md open question was
replaced rather than deleted, and now asks someone with real err2issue
issues to watch a run end to end.
claude-code-action/untouched. It has no equivalent change — itauthenticates with
ANTHROPIC_API_KEYand is unaffected by the Copilotbilling route. Worth a separate look, not this PR.
compile). Guarded by the same
if: github.event.action != 'edited'as theother expensive jobs. The alternative is shipping an installation guide nobody
has executed, which is what this PR is fixing.
max-ai-credits: 300is a judgement call, not a measurement. It isdeliberately well under the 5000 AIC default because a runaway loop is cheaper
to find at 300. Nobody has profiled a real autofix run; the docs say to raise
it after looking at
gh aw logs.bash: ["git log:*", ...]. The colon-wildcard form is not inthe documented examples, but the compiler accepts it, so it stays.
Sources: PAT changelog ·
frontmatter ·
safe outputs ·
auth ·
billing ·
triggering CI ·
using at scale ·
sharing workflows
Generated by Claude Code
Summary by CodeRabbit
New Features
Documentation
Tests