Skip to content

docs: document add-labels safe-output capability in create-agentic-workflow.md #29054

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
Apr 29, 2026
Merged

docs: document add-labels safe-output capability in create-agentic-workflow.md #29054

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
f5caa84
Initial plan
Copilot Apr 29, 2026
77b3363
docs: document add-labels safe-output capability in create-agentic-wo…
Copilot Apr 29, 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
11 changes: 10 additions & 1 deletion .github/aw/create-agentic-workflow.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -545,7 +545,8 @@ These resources contain workflow patterns, best practices, safe outputs, and per
- 📋 **DO NOT include other fields with good defaults** - Let the compiler use sensible defaults unless customization is needed.
- Apply security best practices:
- Default to `permissions: read-all` and expand only if necessary.
- Prefer `safe-outputs` (`create-issue`, `add-comment`, `create-pull-request`, `create-pull-request-review-comment`, `update-issue` for editing, `close-issue` for closing, `dispatch-workflow`) over granting write perms.
- Prefer `safe-outputs` (`create-issue`, `add-comment`, `create-pull-request`, `create-pull-request-review-comment`, `update-issue` for editing, `close-issue` for closing, `add-labels` for labeling, `dispatch-workflow`) over granting write perms.
- ❌ **Anti-pattern**: Do NOT use `gh issue edit --add-label` or `gh label` CLI commands directly in bash — these bypass safe-output controls (rate limiting, audit trails, allow-lists). Use `safe-outputs: add-labels:` instead.
Copy link

Copilot AI Apr 29, 2026

Choose a reason for hiding this comment

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

“Do NOT use gh ... or gh label CLI commands directly in bash” is overly broad: gh label includes read-only operations like gh label list that don’t bypass safe-outputs. Consider narrowing this to the specific write commands/subcommands (e.g., gh issue edit --add-label, gh label create/delete/edit) or explicitly saying “label mutations via gh CLI”.

This issue also appears on line 829 of the same file.

Suggested change
- ❌ **Anti-pattern**: Do NOT use `gh issue edit --add-label` or `gh label` CLI commands directly in bash — these bypass safe-output controls (rate limiting, audit trails, allow-lists). Use `safe-outputs: add-labels:` instead.
- ❌ **Anti-pattern**: Do NOT use `gh issue edit --add-label` or label mutation commands such as `gh label create`, `gh label edit`, or `gh label delete` directly in bash — these bypass safe-output controls (rate limiting, audit trails, allow-lists). Use `safe-outputs: add-labels:` instead.

Copilot uses AI. Check for mistakes.
- For custom write operations to external services (email, Slack, webhooks), use `safe-outputs.jobs:` to create custom safe output jobs.
- Constrain `network:` to the minimum required ecosystems/domains.
- Use sanitized expressions (`${{ steps.sanitized.outputs.text }}`) instead of raw event text.
Expand Down Expand Up @@ -825,6 +826,14 @@ Based on the parsed requirements, determine:
- Creating issues → `safe-outputs: create-issue:`
- Commenting → `safe-outputs: add-comment:`
- Creating PRs → `safe-outputs: create-pull-request:`
- **Applying labels** → `safe-outputs: add-labels:` — use a dedicated `add-labels` safe output, **not** `update-issue` with a `labels` array and **not** `gh issue edit --add-label` in bash (both bypass allow-list enforcement and audit trails). Example:
```yaml
safe-outputs:
add-labels:
allowed: [bug, enhancement, needs-triage] # restrict to safe labels
max: 3
```
The agent calls `add_labels` with a `labels` array; the safe-output job applies them with `issues: write` / `pull-requests: write` permissions. ❌ Anti-pattern: `gh issue edit --add-label <label>` in bash — this bypasses safe-output controls.
- **No action needed** → `safe-outputs: noop:` - **IMPORTANT**: When the agent successfully completes but determines nothing needs to be done, use `noop` to signal completion. This is critical for transparency—it shows the agent worked AND that no output was necessary.
- **Daily reporting workflows** (creates issues/discussions): Add `close-older-issues: true` or `close-older-discussions: true` to prevent clutter
- **Daily improver workflows** (creates PRs): Add `skip-if-match:` with a filter to avoid opening duplicate PRs (e.g., `'is:pr is:open in:title "[workflow-name]"'`)
Expand Down
Loading