Skip to content

docs: surface allowed-teams in agentic mentions config docs #40421

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
pelikhan merged 2 commits into from
Jun 20, 2026
+5 −0
Merged

docs: surface allowed-teams in agentic mentions config docs #40421

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
5a64a3e
Initial plan
Copilot Jun 20, 2026
f83a535
docs: add allowed-teams to mentions example and prose in safe-outputs…
Copilot Jun 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions .github/aw/safe-outputs-runtime.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -142,11 +142,16 @@ description: Safe-output reference for runtime defaults, custom jobs, scripts, a
allow-team-members: true # Allow repository collaborators (default: true)
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)

@github-actions github-actions Bot Jun 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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

\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

- reviewers # bare team-slug (uses current repo's org)
max: 50 # Maximum mentions per message (default: 50)
```

- 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.
Comment on lines 151 to +153

@github-actions github-actions Bot Jun 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-slug for cross-org teams or a bare team-slug to resolve against the current repository's organization.

Should read something like:

Use the fully-qualified org/team-slug form for explicit org targeting (or when the same team-slug exists in multiple orgs), or a bare team-slug to 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.

- **`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 github-actions Bot Jun 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

[/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

\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

@github-actions github-actions Bot Jun 20, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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:org scope
  • 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..."

- `runs-on:` - Runner specification for all safe-outputs jobs (string)
- Defaults to `ubuntu-slim` (1-vCPU runner)
- Examples: `ubuntu-latest`, `windows-latest`, `self-hosted`
Expand Down
Loading