[FAQ] Add: controlling the agent's working branch at runtime#29377
[FAQ] Add: controlling the agent's working branch at runtime#29377
Conversation
Adds a new entry under 'Workflow Design' explaining how to use preserve-branch-name and recreate-ref to have the agent apply changes to a specific branch name extracted at runtime (e.g., from a Jira issue). Closes github/agentic-workflows#513 Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
📰 DEVELOPING STORY: Smoke Copilot ARM64 reports was cancelled. Our correspondents are investigating the incident... |
Comment MemoryNote This comment is managed by comment memory.It stores persistent context for this thread in the code block at the top of this comment. |
|
❌ Smoke Multi PR failed to create multiple PRs. Check the logs. |
|
Hey One small flag: no test files were changed alongside this docs update. For pure Markdown FAQ entries this is often expected, but if the project has any doc-lint, link-checker, or content validation tests that should be updated or verified, it's worth confirming they still pass. If you'd like a hand, you can assign this prompt to your coding agent:
|
|
@chrizbo looks like it creates 2 FAQ for the same question |
There was a problem hiding this comment.
Pull request overview
Adds a new FAQ entry under Workflow Design describing how to control the agent’s pull-request branch name at runtime (including reuse of an existing remote branch name) via create-pull-request safe output configuration.
Changes:
- Adds an FAQ entry explaining
preserve-branch-name: trueandrecreate-ref: truefor runtime branch naming and collision behavior. - Provides an example instruction for extracting a branch name from an issue body and using it when creating a PR.
- Adds a NOTE clarifying that the agent still starts from the configured base branch.
Show a summary per file
| File | Description |
|---|---|
| docs/src/content/docs/reference/faq.md | Adds a new FAQ entry documenting runtime control of PR branch naming and remote-branch collision behavior. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
- Files reviewed: 1/1 changed files
- Comments generated: 4
|
|
||
| ```markdown | ||
| Read the issue body and extract the branch name from the line starting with | ||
| "Use existing branch:". Use that name when calling `create_pull_request`. |
There was a problem hiding this comment.
To make this actionable, it would help to mention the actual tool input name: the extracted name should be passed as the branch field in the create_pull_request call (per the tool schema).
| "Use existing branch:". Use that name when calling `create_pull_request`. | |
| "Use existing branch:". Pass that name as the `branch` field when calling `create_pull_request`. |
| The `create-pull-request` safe output always creates a new branch, but you can control its name and make it reuse an existing remote branch. Set these two fields in your workflow frontmatter: | ||
|
|
||
| ```yaml wrap | ||
| safe-outputs: | ||
| create-pull-request: | ||
| preserve-branch-name: true # omit random salt suffix from agent-specified name | ||
| recreate-ref: true # force-reset remote branch if it already exists |
There was a problem hiding this comment.
The phrasing here is a bit misleading: recreate-ref: true does not “reuse” the existing remote branch contents; it force-deletes/recreates the remote ref (force-push semantics) to point at the agent’s HEAD. Consider aligning terminology with the existing reference docs (e.g., “force-delete and recreate the remote branch ref”) and updating the inline comment that currently says “force-reset”.
| recreate-ref: true # force-reset remote branch if it already exists | ||
| ``` | ||
|
|
||
| With `preserve-branch-name: true`, the agent's branch name (e.g., `feature/abc-123-my-change`) is used as-is instead of having a random hex suffix appended. With `recreate-ref: true`, if that branch already exists remotely, it is force-reset to the agent's current HEAD rather than falling back to creating an issue. |
There was a problem hiding this comment.
This sentence implies the collision fallback is always “creating an issue”, but per the safe-outputs docs it only falls back to an issue when fallback-as-issue: true (default); otherwise PR creation fails. Please qualify the wording to reflect the fallback-as-issue setting.
| With `preserve-branch-name: true`, the agent's branch name (e.g., `feature/abc-123-my-change`) is used as-is instead of having a random hex suffix appended. With `recreate-ref: true`, if that branch already exists remotely, it is force-reset to the agent's current HEAD rather than falling back to creating an issue. | |
| With `preserve-branch-name: true`, the agent's branch name (e.g., `feature/abc-123-my-change`) is used as-is instead of having a random hex suffix appended. With `recreate-ref: true`, if that branch already exists remotely, it is force-reset to the agent's current HEAD rather than using the normal branch-collision behavior (by default, falling back to creating an issue when `fallback-as-issue: true`; otherwise failing PR creation). |
| To pass the branch name from a Jira issue body (or any issue body), instruct the agent in your workflow's markdown: | ||
|
|
||
| ```markdown | ||
| Read the issue body and extract the branch name from the line starting with | ||
| "Use existing branch:". Use that name when calling `create_pull_request`. | ||
| ``` | ||
|
|
||
| The agent reads the triggering issue body as part of its context, so no extra integration is needed when the branch name is embedded there. For richer Jira data (status, custom fields), use a [custom safe output](/gh-aw/reference/custom-safe-outputs/) or Jira MCP server. |
There was a problem hiding this comment.
“Jira issue body” is not part of the agent context unless you fetch it via an integration (e.g., MCP/custom job) or copy the relevant text into the triggering GitHub issue body. Consider rewording to distinguish “triggering GitHub issue body” (available by default) from “Jira issue body” (requires integration).
Adds a new FAQ entry under Workflow Design answering the common question of how to make the agent apply changes to a specific branch name specified at runtime — for example, a branch name embedded in a Jira issue description.
The entry covers:
preserve-branch-name: trueto use the agent-supplied branch name as-isrecreate-ref: trueto force-reset the remote branch if it already exists[!NOTE]callout clarifying that the agent starts from the base branch (it doesn't literally check out the named branch before making changes)Source issue: github/agentic-workflows#513
This is a new entry; no existing FAQ entry covered this topic.