Skip to content

docs(site): document target-branches and infer-target-from-checkout-ref for create-pull-request #1449

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
jamesadevine merged 1 commit into from
Jul 13, 2026
Merged

docs(site): document target-branches and infer-target-from-checkout-ref for create-pull-request #1449

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
14 changes: 13 additions & 1 deletion site/src/content/docs/reference/safe-outputs.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -270,7 +270,19 @@ This hybrid approach combines:
Note: The source branch name is auto-generated from a sanitized version of the PR title plus a unique suffix (e.g., `agent/fix-bug-in-parser-a1b2c3`). This format is human-readable while preventing injection attacks.

**Configuration options (front matter):**
- `target-branch` - Target branch to merge into (default: "main")
- `target-branch` - Target (base) branch the PR merges into (default: `"main"`). A plain literal branch name applied to every repo unless overridden by `target-branches` or `infer-target-from-checkout-ref`.
- `target-branches` - Optional map of per-repository target-branch overrides, keyed by the repository alias the agent passes to `create-pull-request` (`self` or a `checkout:` alias). Highest precedence. Useful when a multi-checkout ("meta repo") agent needs to open a PR into a different base branch per repo.
```yaml
safe-outputs:
create-pull-request:
target-branch: main # default for self + any repo without an override
target-branches:
docs: gh-pages # PRs to the "docs" checkout always target gh-pages
sdk: release/v2 # PRs to the "sdk" checkout always target release/v2
```
- `infer-target-from-checkout-ref` - Optional bool (default: `false`). When `true`, a checkout repo with no explicit `target-branches` entry targets its own `repos: ref` (the branch it was checked out at). `self` and repos without a known ref fall back to `target-branch`. Only branch refs (`refs/heads/*`) are valid PR targets — repos checked out at a tag ref (`refs/tags/*`) trigger a compile-time warning and should be given an explicit `target-branches` entry instead.

**Per-repo target resolution precedence** (for a repo alias `R`): `target-branches[R]` → (if `infer-target-from-checkout-ref`) `R`'s checkout ref → `target-branch` → `"main"`.
- `draft` - Whether to create the PR as a draft (default: **true**). Set to `false` to publish the PR immediately. **Note:** `auto-complete` is silently skipped on draft PRs -- set `draft: false` when using `auto-complete: true`.
- `auto-complete` - Set auto-complete on the PR (default: false). Requires `draft: false` to take effect.
- `delete-source-branch` - Delete source branch after merge (default: true)
Expand Down