Safe Outputs (Pull Requests) | GitHub Agentic Workflows
Skip to main content Safe Outputs (Pull Requests) This page covers pull-request-focused safe outputs: create-pull-request , update-pull-request , close-pull-request , approve-workflow-run , merge-pull-request (experimental), create-pull-request-review-comment , submit-pull-request-review , reply-to-pull-request-review-comment , resolve-pull-request-review-thread , push-to-pull-request-branch , and add-reviewer . create-pull-request , push-to-pull-request-branch , and merge-pull-request enforce Protected Files by default.
For other safe-output types, see Safe Outputs . Pull Request Creation ( create-pull-request: ) Section titled “Pull Request Creation (create-pull-request:)” Creates a PR with the agent’s code changes. If PR creation is blocked (for example, by organization settings), it falls back to opening an issue; set fallback-as-issue: false to disable this. The default max: 1 is a per-workflow-run quota shared by all agents and sub-agents , not a per-agent limit.
Raise max when parallel agents or multiple independent PRs are needed. Excess create_pull_request calls are rejected. safe-outputs : create-pull-request : title-prefix : " [ai] " # prefix for titles labels : [ automation ] # labels to attach reviewers : [ user1 , copilot ] # reviewers (use 'copilot' for bot) team-reviewers : [ platform-reviewers ] # team slugs to request as reviewers assignees : [ user1 ] # assignees for the created PR and any fallback issue draft : true # create as draft — enforced as policy (default: true) max : 3 # max PRs per run (default: 1) expires : 14 # auto-close after N days (same-repo only; also accepts 2h, 7d, 2w, 1m, 1y) if-no-changes : " warn " # "warn" (default), "error", or "ignore" target-repo : " owner/repo " # upstream repository that receives the PR head-repo : " automation/fork " # optional automation-owned fork that receives the branch push allowed-repos : [ " org/repo1 " , " org/repo2 " , " automation/fork " ] # allowlisted upstream/head repositories base-branch : " vnext " # PR target branch (default: github.base_ref || github.ref_name) allowed-base-branches : # allow agent to override base branch at runtime (glob patterns) - main - release/* allowed-branches : # restrict agent-selected source branch names (glob patterns) - feature/* - release/* stacked : true # allow stacked pull requests (default: true) fallback-as-issue : false # disable issue fallback (default: true) auto-close-issue : false # don't auto-add "Fixes #N" to PR description (default: true) normalize-closing-keywords : true # strip backticks around recognized issue-closing keywords in PR body text preserve-branch-name : true # omit random salt suffix from branch name (default: false) recreate-ref : true # force-recreate remote branch when it already exists (requires preserve-branch-name; default: false) exclude-lock-yml : true # omit compiled workflow locks (default: false) excluded-files : # strip these files from the patch entirely - " **/*.lock " - " dist/** " max-patch-files : 300 # max unique files in the patch (default: 100) max-patch-size : 2048 # max patch size in KB (default: 4096) github-token : ${{ secrets.UPSTREAM_PR_TOKEN }} # optional credential for upstream PR creation head-github-token : ${{ secrets.FORK_PUSH_TOKEN }} # optional credential for fork branch writes head-github-app : # optional GitHub App to mint the fork credential at runtime client-id : ${{ vars.FORK_APP_CLIENT_ID }} private-key : ${{ secrets.FORK_APP_PRIVATE_KEY }} github-token-for-extra-empty-commit : ${{ secrets.CI_TOKEN }} # optional token to push empty commit triggering CI signed-commits : true # signed commits via GitHub APIs (default: true); set false to use git push directly protected-files : fallback-to-issue # push branch, create review issue if protected files modified target-repo names the upstream repository that owns the base branch. head-repo , when set, names the automation-owned fork that receives the pushed branch.
When they differ, the created PR uses an owner-qualified head ( fork-owner:branch ), and both repositories must be allowlisted. See Cross-Repository Operations for target-repo , allowed-repos , and authentication. Steering issues Section titled “Steering issues” Configure steering independently at safe-outputs.steer . Steering does not pre-create or override a branch, so branch-prefix , cross-repository targets, branch policies, multiple outputs, and checkout configuration behave as usual.
Branch targeting Section titled “Branch targeting” base-branch sets the PR target. It defaults to github.base_ref on pull request events and github.ref_name on push events. To let the agent pick the target at runtime, use allowed-base-branches : the agent’s base value is accepted only if it matches a configured glob. allowed-branches restricts which source branch names the agent may use. The effective branch (agent-provided, or the checkout branch as a fallback) must match a configured glob.
Stacked pull requests Section titled “Stacked pull requests” A stacked pull request targets another pull request’s branch instead of the default base, so a chain of dependent changes can be reviewed and merged one piece at a time. For example, PR 1 ( feature-1 ) targets main , PR 2 ( feature-2 ) targets feature-1 , and PR 3 ( feature-3 ) targets feature-2 . Set max above 1 and emit one create_pull_request output per level, in dependency order.
Each base must already exist when its PR is created: safe-outputs : create-pull-request : max : 3 preserve-branch-name : true # keeps `base` values predictable across the stack { "type" : " create_pull_request " , "title" : " Step 1 " , "body" : " ... " , "branch" : " feature-1 " } { "type" : " create_pull_request " , "title" : " Step 2 " , "body" : " ... " , "branch" : " feature-2 " , "base" : " feature-1 " , "stack_position" : 2 , "stack_root" : " main " } { "type" : " create_pull_request " , "title" : " Step 3 " , "body" : " ...
" , "branch" : " feature-3 " , "base" : " feature-2 " , "stack_position" : 3 , "stack_root" : " main " , "dependencies" : [ " feature-1 " , " feature-2 " ]} Behavior: A base that names a branch from a PR created earlier in the same run is accepted without allowed-base-branches . It resolves to the branch actually pushed, which is salted unless preserve-branch-name: true is set. Any other base override requires allowed-base-branches .
The base branch must exist before the PR is created, or the output fails. Circular dependencies are rejected. The PR body records the stack: a Depends on #N reference for each same-run dependency, and a <!-- gh-aw-stack: ... --> comment holding base , stack_position , stack_root , and dependencies . Disabling stacked pull requests (GitHub Enterprise Server) Section titled “Disabling stacked pull requests (GitHub Enterprise Server)” Stacked pull requests may be unavailable on GitHub Enterprise Server.
Set stacked: false so misuse fails fast. Any create_pull_request output whose base differs from the default base is then rejected with an explanatory error. PRs targeting the default base keep working, and stack metadata is still recorded, so a workflow can move between instances without editing its prompt. safe-outputs : create-pull-request : stacked : false Migrating an existing workflow to a stack Section titled “Migrating an existing workflow to a stack” Raise max to the stack size, set preserve-branch-name: true so each base matches the original branch name, and have the agent emit PRs root-first, each with base pointing to the previous branch.
On GitHub Enterprise Server, also add stacked: false and keep the agent targeting the default base branch. Keep stacks to three or four PRs, use explicit branch and base names, and merge from the root upward. Runtime reviewers and assignees Section titled “Runtime reviewers and assignees” reviewers , team-reviewers , and assignees accept either a static list or a single GitHub Actions expression string. This lets you route
The rest of this page is on the live site.