Safe-outputs `add_comment` mentions sanitization being too restrictive

[ivancea]

Currently, add_comment sanitization requires to list all members that may be mentioned.
This is too restrictive, and doesn't allow organizations to freely mention their own engineers.

A few possible solutions:

• Allow full teams by just declaring the team name
• Configuration to disable sanitization for mentions, as a fallback

[pelikhan]

/scout research if some of these questions can be answered

[github-actions]

🔭 Recon complete! Scout has charted the territory. Map ready! 🗺️

[github-actions]

🔍 Scout Research Report

Triggered by @pelikhan (/scout research if some of these questions can be answered)

Executive Summary

Good news: most of what this issue asks for already exists in the codebase as the safe-outputs.mentions config — it just isn't surfaced in the user-facing docs, which is likely why it reads as "too restrictive." Specifically:

• Request Add workflow: githubnext/agentics/weekly-research #2 — "disable sanitization for mentions as a fallback" → already supported today via safe-outputs: { mentions: true } (with one strict-mode caveat).
• Request rejig docs #1 — "allow full teams by just declaring the team name" → NOT supported, and it hits a hard GitHub token constraint. The existing allow-team-members option resolves repo collaborators, not org teams, which is exactly the org-engineer gap this issue describes.

Click to expand detailed findings

Research Findings

What already exists: the safe-outputs.mentions config

The compiler already parses a mentions block (MentionsConfig in pkg/workflow/compiler_types.go:773, schema at pkg/parser/schemas/main_workflow_schema.json:10195). Runtime resolution lives in actions/setup/js/resolve_mentions_from_payload.cjs and resolve_mentions.cjs. Options:

Field	Default	Behavior
mentions: true	—	Allow ALL mentions, no escaping (errors in strict mode)
mentions: false	—	Escape every mention
allow-team-members	true	Allow repo collaborators (first 30 direct, any permission, non-bot)
allow-context	true	Allow issue/PR/discussion authors, assignees, commenters
allowed: [names]	[]	Explicit always-allowed list (also the only way to allow bots)
max	50	Max mentions per message

Q2: "Disable sanitization for mentions, as a fallback" — ✅ already answerable

This is the boolean form safe-outputs: { mentions: true }, documented in the schema as "true = always allow mentions (error in strict mode)" (main_workflow_schema.json:10200). For orgs that want unrestricted mentions, this is the escape hatch. Two finer-grained alternatives that avoid the strict-mode error: list the engineers under mentions.allowed: [...], or rely on allow-context/allow-team-members.

Caveat: by design mentions: true is rejected in strict mode, so it's not a fallback in strict-mode workflows. If a strict-mode-compatible "allow all" is wanted, that's a small new behavior, not a new mechanism.

Q1: "Allow full teams by just declaring the team name" — ❌ real gap + token constraint

The current allow-team-members is a misnomer: it does not expand a GitHub org/team. It calls repos.listCollaborators + repos.getCollaboratorPermissionLevel / users.getByUsername (resolve_mentions.cjs:74-156) — i.e. it allows direct repo collaborators only. An org engineer who is not a collaborator on that specific repo is still escaped, which is precisely the pain in this issue ("doesn't allow organizations to freely mention their own engineers").

Note the mention regex does already capture @org/team slugs (resolve_mentions.cjs:40, the (?:\/[A-Za-z0-9._-]+)? group), but resolution treats the slug as a username, so getByUsername fails and it is denied. So the plumbing partially anticipates teams but the resolution path doesn't implement them.

Hard constraint for implementing team expansion: resolving a team slug needs GET /orgs/{org}/teams/{team_slug}/members, and the default Actions GITHUB_TOKEN cannot read org teams — confirmed as a documented design limitation (community discussion #113519: error fetching organization teams: GraphQL: Resource not accessible by integration (organization.teams)). Team expansion would therefore require a PAT or GitHub App installation token with org members:read. Any feature here must degrade gracefully when only the default token is present.

Recommendations

1. Close the doc gap first (cheapest win). The mentions config is essentially undocumented in docs/src/content/docs/reference/safe-outputs.md (only max-bot-mentions is described). Documenting mentions: true / allowed: / allow-context likely resolves the practical complaint behind Q2 without code.
2. Rename/clarify allow-team-members. It allows collaborators, not teams — the name actively misleads and is probably the root of this issue's framing. Consider an alias like allow-collaborators (keep the old key) and document the distinction.
3. For real Q1 support, add an allowed-teams: ["org/team"] (or let allowed: accept org/team slugs) that expands members via the Teams API, gated behind a provided org-scoped token, with a clear warning + fallback-to-escape when the default GITHUB_TOKEN can't read the org. Cache per-team like the existing collaborator cache.
4. Strict mode: if an "allow all engineers" fallback must work under strict mode, prefer the explicit allowed: list (auditable) over a blanket mentions: true.

Key Sources

• Existing config: pkg/workflow/compiler_types.go:773, pkg/parser/schemas/main_workflow_schema.json:10195
• Runtime resolution: actions/setup/js/resolve_mentions_from_payload.cjs, actions/setup/js/resolve_mentions.cjs
• Token limitation: community discussion #113519 — org.teams not accessible by integration, [GITHUB_TOKEN permissions changelog]((github.blog/redacted)

Suggested Next Steps

1. Document the existing mentions block in safe-outputs.md (answers Q2 with zero code).
2. Decide on renaming/aliasing allow-team-members → allow-collaborators to remove the misnomer.
3. Scope an allowed-teams feature with an explicit org-token requirement + graceful degradation as the proper Q1 fix.

🔭 Intelligence gathered by Scout · 120.3 AIC · ⌖ 12.9 AIC · ⊞ 6.4K · ◷