Safe Outputs | GitHub Agentic Workflows
Skip to main content Safe Outputs The safe-outputs: (validated GitHub operations) element of your workflow’s frontmatter declares that your agentic workflow should conclude with optional automated actions based on the agentic workflow’s output. This enables your workflow to write content that is then automatically processed to create GitHub issues, comments, pull requests, or add labels - all without giving the agentic portion of the workflow any write permissions.
Safe outputs separate action requests from execution: the agent requests actions through structured output, and separate permission-controlled jobs execute permitted requests. This separation limits the agent’s direct permissions and supports validation, auditability and per-operation limits. Configured outputs may publish content, update metadata or merge pull requests automatically. Review requirements depend on the output configuration and applicable policy gates.
When no safe-outputs: section is present (or when only system types are configured), create-issue is automatically enabled with conservative defaults ( max: 1 , labels and title-prefix set to the workflow ID). Setting create-issue: false disables the create_issue tool and its automatic reporting instruction while leaving system outputs enabled: safe-outputs : create-issue : false Example: safe-outputs : create-issue : The agent requests issue creation; a separate job with issues: write creates it.
CLI Payloads Section titled “CLI Payloads” When the runtime exposes safe outputs through the safeoutputs CLI, tool names use underscores, such as create_issue . Run safeoutputs --help to list available tools and safeoutputs create_issue --help for that tool’s schema. Calls request real actions for downstream processing; they are not previews. Pass a complete JSON object as one single-quoted shell argument: Terminal window safeoutputs create_issue ' {"title":"Documentation findings","body":"First finding.\nSecond finding."} ' Inside JSON strings, encode newlines as \n , double quotes as \" , backslashes as \\ , and apostrophes as \u0027 to preserve the surrounding shell quote.
For a Markdown report already saved in a file, per-field stdin avoids manually escaping its body: Terminal window cat /tmp/gh-aw/agent/report.md | safeoutputs create_issue --title " Documentation findings " --body . The --body . form supplies the text to one field. The bare safeoutputs create_issue . form instead requires the entire stdin content to be a valid JSON object. Raw Markdown is not valid input for that bare form, and {"body": .} is not valid JSON.
Use only tools and shell operations available in the workflow’s runtime. Output Dependencies Section titled “Output Dependencies” Each recorded safe-output call returns a unique, compact URL-safe output_id , such as so_AbCdEf012345 . This identifies the queued operation, not a created issue or pull request. It is distinct from temporary_id ( aw_… ), which remains the mechanism for referencing newly created resources.
For handler-managed safe outputs, depends-on is available by default and is optional; omit it to run an operation independently. When provided, it accepts one output_id or a nonempty array of distinct identifiers. All prerequisites must complete successfully before the dependent operation runs. For example, after a call returns the identifier above: { "item_number" : 123 , "body" : " The prerequisite update completed.
" , "depends-on" : " so_AbCdEf012345 " } The identifier acknowledges recording, not execution success. If a prerequisite fails, its dependents fail without executing, including transitive dependents. Skipped, cancelled, staged, deferred, or delegated results do not establish success. Missing, ambiguous, or cyclic dependencies also fail closed. Independent outputs retain their existing behavior and policy checks. submit_pull_request_review and create_pull_request_review_comment can be prerequisites.
Inline comments and the review body are buffered and submitted together at the end of message processing, before dependent outputs run. Buffering alone does not confirm success: dependents wait for submission and run only if their prerequisite was actually published. Review comments released by a dependency are submitted in a subsequent batch. Do not make a review depend on its own inline comments: they are included automatically.
If such a dependency is supplied, the review and its comments are submitted together; other dependents still wait for publication. If the review cannot run, its buffered batch is not submitted without the review. If a required inline comment cannot be anchored, the batch fails instead of falling back to a review without that comment. Avoid indirect cycles too: a review cannot wait for an output that itself requires publication of a comment in that same review.
Dependencies apply within a single safe-output processing pass (and within the same Claim in queue workflows). Custom safe jobs, call_workflow , push_repo_memory , upload_asset , noop , and out-of-band diagnostics ( report_incomplete , report_missing_tool , report_missing_data ) reject depends-on . upload_code_coverage , dispatch_workflow , dispatch_repository , and custom action outputs delegate effects outside this manager, so they cannot establish successful prerequisites.
Dependencies do not provide rollback for operations that have already succeeded. Available Safe Output Types Section titled “Available Safe Output Types” The tables below summarize the built-in safe output handlers. noop , report-missing-tool , and report-missing-data are always available, and create-issue is auto-injected only when no non-system safe outputs are configured and it is not explicitly disabled. Issues & Discussions Section titled “Issues & Discussions” Output Key Description Create Issue create-issue Create GitHub issues (max: 1) Update Issue update-issue Update issue properties or artifacts (max: 1) Close Issue close-issue Close issues with comment (max: 1) Link Sub-Issue link-sub-issue Link issues as sub-issues (max: 1) Create Discussion create-discussion Create GitHub discussions (max: 1) Update Discussion update-discussion Update discussion title, body, or labels (max: 1) Close Discussion close-discussion Close discussions with comment and resolution (max: 1) Pull Requests Section titled “Pull Requests” Output Key Description Create PR create-pull-request Create pull requests with code changes (default max: 1, configurable) Update PR update-pull-request Update PR title or body (max: 1) Close PR close-pull-request Close pull requests without merging (max: 10) Approve Workflow Run approve-workflow-run Approve a pending workflow run in the “action required” state (max: 1) Merge PR merge-pull-request Merge pull requests after policy gates pass (max: 1, experimental) PR Review Comments create-pull-request-review-comment Create review comments on code lines (max: 10) Reply to PR Review Comment reply-to-pull-request-review-comment Reply to existing review comments (max: 10) Resolve PR Review Thread resolve-pull-request-review-thread Resolve review threads after addressing feedback (max: 10) Add Reviewer add-reviewer Add reviewers to pull requests (max: 3) Push to PR Branch push-to-pull-request-branch Push changes to PR branch (default max: 1, configurable; cross-repo supported via target-repo when the target repository is checked out) Labels, Assignments & Reviews Section titled “Labels, Assignments & Reviews” Output Key Description Add Comment add-comment Post comments on issues, PRs, or discussions (max: 1) Hide Comment hide-comment Hide comments on issues, PRs, or discussions (max: 5) Add Labels add-labels Add labels to issues or PRs (max: 5 calls) Remove Labels remove-labels Remove labels from issues or PRs (max: 3) Assign Milestone assign-milestone Assign issues to milestones (max: 1) Assign to Agent assign-to-agent Assign Copilot coding agent to issues or PRs (max: 1) Assign
The rest of this page is on the live site.