docs: surface allowed-teams in agentic mentions config docs#40421
Conversation
…-runtime.md Co-authored-by: pelikhan <4175913+pelikhan@users.noreply.github.com>
allowed-teams in agentic mentions config docs
|
🧠 Matt Pocock Skills Reviewer has completed the skills-based review. ✅ |
|
✅ Design Decision Gate 🏗️ completed the design decision gate check. No ADR enforcement needed: PR #40421 does not have the 'implementation' label and has 0 new lines of code in business logic directories (only 1 file changed, a docs/markdown update). |
|
✅ PR Code Quality Reviewer completed the code quality review. |
|
✅ Test Quality Sentinel completed test quality analysis. No test files were added or modified in this PR. Test Quality Sentinel skipped. |
There was a problem hiding this comment.
Pull request overview
Updates the safe-outputs runtime reference documentation to surface the previously-added safe-outputs.mentions.allowed-teams option so workflow authors (and agents) can discover and use team-based mention allowlisting.
Changes:
- Adds
allowed-teamsto thesafe-outputs.mentionsYAML example. - Documents runtime team membership resolution semantics (org-qualified vs bare slugs, bot exclusion).
- Documents the
read:orgrequirement and token alternatives, including graceful-degradation behavior.
Show a summary per file
| File | Description |
|---|---|
| .github/aw/safe-outputs-runtime.md | Documents mentions.allowed-teams usage, semantics, and required token scope for runtime resolution. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 2
| - Team members include collaborators with any permission level (excluding bots unless explicitly listed) | ||
| - Context mentions include issue/PR authors, assignees, and commenters | ||
| - `allowed-teams` resolves team membership from the GitHub API at runtime; bot accounts are excluded. Use `org/team-slug` for cross-org teams or a bare `team-slug` to resolve against the current repository's organization. |
| - Team members include collaborators with any permission level (excluding bots unless explicitly listed) | ||
| - Context mentions include issue/PR authors, assignees, and commenters | ||
| - `allowed-teams` resolves team membership from the GitHub API at runtime; bot accounts are excluded. Use `org/team-slug` for cross-org teams or a bare `team-slug` to resolve against the current repository's organization. | ||
| - **`allowed-teams` requires `read:org` scope.** The default `GITHUB_TOKEN` does **not** include this scope. Provide a classic PAT with `read:org`, a fine-grained PAT with the "Members" permission (read), or a GitHub App installation token with the "Members" permission (read) via `safe-outputs.github-token:` or `safe-outputs.github-app:`. If the token lacks the required scope, team lookup fails with a warning and the workflow continues without those team members in the allowlist. |
![github-actions[bot]](https://avatars.githubusercontent.com/in/15368?s=60&v=4){kind=small}
There was a problem hiding this comment.
Skills-Based Review 🧠
Applied /grill-with-docs — approving with two minor suggestions.
📋 Key Themes & Highlights
Suggestions
- Line 146 —
(cross-org)label:org/team-slugis the fully-qualified form that works for any org (including the current one), not only cross-org situations. A label like# fully-qualified form (works for any org)is more accurate. - Line 154 — dense scope-caveat bullet: The single bullet covers scope requirement, GITHUB_TOKEN limitation, three token alternatives, and graceful-degradation in one sentence. Splitting into two bullets would match the existing doc style and be easier to parse.
Positive Highlights
- ✅ Both resolution formats (
org/team-slugand bareteam-slug) shown with inline comments - ✅
read:orgscope requirement and all three token alternatives clearly documented - ✅ Graceful-degradation behaviour captured — agents know the workflow won't fail on missing scope
- ✅ Terminology (
safe-outputs.github-token:,safe-outputs.github-app:) is consistent with existing doc entries
🧠 Reviewed using Matt Pocock's skills by Matt Pocock Skills Reviewer · 61.3 AIC · ⌖ 7.4 AIC · ⊞ 6.9K
| allow-context: true # Allow mentions from event context (default: true) | ||
| allowed: [copilot, user1] # Always allow specific users/bots | ||
| allowed-teams: # Allow all members of named GitHub teams | ||
| - myorg/eng # org/team-slug format (cross-org) |
There was a problem hiding this comment.
[/grill-with-docs] The (cross-org) label is slightly misleading: org/team-slug is the fully-qualified form that works for any org, not only cross-organization ones — you'd write myorg/eng even when your repo already lives in myorg.\n\n
💡 Suggested wording
\n\nyaml\n - myorg/eng # fully-qualified form (works for any org)\n - reviewers # bare team-slug (resolves against current repo's org)\n\n\nThe current (cross-org) label could lead an agent to believe org/team-slug is only for cross-organization scenarios, rather than the general explicit-qualifier form.\n\n| - Team members include collaborators with any permission level (excluding bots unless explicitly listed) | ||
| - Context mentions include issue/PR authors, assignees, and commenters | ||
| - `allowed-teams` resolves team membership from the GitHub API at runtime; bot accounts are excluded. Use `org/team-slug` for cross-org teams or a bare `team-slug` to resolve against the current repository's organization. | ||
| - **`allowed-teams` requires `read:org` scope.** The default `GITHUB_TOKEN` does **not** include this scope. Provide a classic PAT with `read:org`, a fine-grained PAT with the "Members" permission (read), or a GitHub App installation token with the "Members" permission (read) via `safe-outputs.github-token:` or `safe-outputs.github-app:`. If the token lacks the required scope, team lookup fails with a warning and the workflow continues without those team members in the allowlist. |
There was a problem hiding this comment.
[/grill-with-docs] This bullet does a lot of work in one sentence: scope requirement, GITHUB_TOKEN limitation, three token alternatives, and graceful-degradation behaviour. Consider splitting it for easier agent and human parsing.\n\n
💡 Suggested split
\n\nmarkdown\n - **`allowed-teams` requires `read:org` scope.** The default `GITHUB_TOKEN` does **not** include this scope; supply a classic PAT with `read:org`, a fine-grained PAT with the "Members" permission (read), or a GitHub App installation token with the "Members" permission (read) via `safe-outputs.github-token:` or `safe-outputs.github-app:`.\n - If the token lacks `read:org`, team lookup fails with a warning and the workflow continues without those team members in the allowlist (graceful degradation).\n\n\nThis mirrors the existing doc style where requirement and fallback behaviour are separate bullets.\n\n
There was a problem hiding this comment.
🔎 Code quality review by PR Code Quality Reviewer · 122.9 AIC · ⌖ 7.83 AIC · ⊞ 5.1K
|
|
||
| - Team members include collaborators with any permission level (excluding bots unless explicitly listed) | ||
| - Context mentions include issue/PR authors, assignees, and commenters | ||
| - `allowed-teams` resolves team membership from the GitHub API at runtime; bot accounts are excluded. Use `org/team-slug` for cross-org teams or a bare `team-slug` to resolve against the current repository's organization. |
There was a problem hiding this comment.
org/team-slug is mislabeled as a "cross-org" format — it is the fully-qualified format that works for any org (same or different), and restricting its description to cross-org will cause agents to avoid it for same-org teams.
💡 Suggested fix
The current prose:
Use
org/team-slugfor cross-org teams or a bareteam-slugto resolve against the current repository's organization.
Should read something like:
Use the fully-qualified
org/team-slugform for explicit org targeting (or when the same team-slug exists in multiple orgs), or a bareteam-slugto implicitly resolve against the current repository's organization.
The inline YAML comment on the myorg/eng example (# org/team-slug format (cross-org)) has the same problem — update to # fully-qualified org/team-slug format.
Why it matters for agents: An agent following this doc will only use org/team-slug when it knows it's targeting a different org, defaulting to bare slugs otherwise. If the same slug resolves differently across orgs the token has access to, or the author simply wants explicit org binding, they have no signal from this doc that the qualified form is valid for their case.
| - Team members include collaborators with any permission level (excluding bots unless explicitly listed) | ||
| - Context mentions include issue/PR authors, assignees, and commenters | ||
| - `allowed-teams` resolves team membership from the GitHub API at runtime; bot accounts are excluded. Use `org/team-slug` for cross-org teams or a bare `team-slug` to resolve against the current repository's organization. | ||
| - **`allowed-teams` requires `read:org` scope.** The default `GITHUB_TOKEN` does **not** include this scope. Provide a classic PAT with `read:org`, a fine-grained PAT with the "Members" permission (read), or a GitHub App installation token with the "Members" permission (read) via `safe-outputs.github-token:` or `safe-outputs.github-app:`. If the token lacks the required scope, team lookup fails with a warning and the workflow continues without those team members in the allowlist. |
There was a problem hiding this comment.
Three precision gaps in the scope/permissions caveat sentence that will cause agents to misread this when creating tokens or diagnosing failures.
💡 Breakdown and suggested fix
1. read:org "scope" conflation across token types
The sentence leads with "allowed-teams requires read:org scope" and then lists fine-grained PATs and GitHub Apps. Classic PATs use OAuth scopes (read:org); fine-grained PATs and GitHub App installation tokens use permissions, not scopes. An agent creating a fine-grained PAT will look for a read:org scope entry in the GitHub UI and not find one.
Suggested split:
- Classic PAT:
read:orgscope- Fine-grained PAT: organization Members permission (read)
- GitHub App: organization Members permission (read)
2. Fine-grained PAT "Members" needs "organization-level" qualifier
GitHub fine-grained PATs separate repository-level and organization-level permissions. "Members" exists only under organization permissions, not repository permissions. Without the qualifier, an agent enabling permissions for a fine-grained PAT will look in the wrong section.
3. Graceful degradation is stated only for scope failure, not team-not-found
"If the token lacks the required scope, team lookup fails with a warning and the workflow continues without those team members in the allowlist."
This implies graceful degradation is scoped only to auth failures. A typo in a team slug (reviewes instead of reviewers) also silently produces no members with no hard error. Agents have no guidance that a misconfigured slug produces an identical silent outcome and cannot be detected from workflow failure alone. The sentence should generalize: "If team lookup fails for any reason (missing scope, non-existent team, rate limit), the workflow continues..."
The
allowed-teamsoption added tosafe-outputs.mentionsin #40368 was missing from.github/aw/safe-outputs-runtime.md— the doc surface agents read when authoring workflows — meaning agents had no way to discover or use the feature.Changes
.github/aw/safe-outputs-runtime.md— updated thementions:entry:allowed-teams:to the YAML example with both resolution formatsorg/team-slugvs bareteam-slugsemanticsread:orgscope caveat with token alternatives (github-token:/github-app:) and graceful-degradation behavior