Skip to content

[FAQ] Add: controlling the agent's working branch at runtime #29377

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 1 commit into from
Apr 30, 2026
+27 −0
Merged

[FAQ] Add: controlling the agent's working branch at runtime #29377

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
27 changes: 27 additions & 0 deletions docs/src/content/docs/reference/faq.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -526,6 +526,33 @@ One workflow is simpler to maintain and good for learning, while multiple workfl

Either approach works well. AI-assisted authoring using `/agent agentic-workflows create` in GitHub Copilot Chat provides interactive guidance with automatic best practices, while manual editing gives full control and is essential for advanced customizations. See [Creating Workflows](/gh-aw/setup/creating-workflows/) for AI-assisted approach, or [Reference documentation](/gh-aw/reference/frontmatter/) for manual configuration.

### Can the agent use an existing branch specified at runtime (e.g., from a Jira issue)?

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
Comment on lines +531 to +537
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

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

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”.

Copilot uses AI. Check for mistakes.
```

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.
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

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

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.

Suggested change
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).

Copilot uses AI. Check for mistakes.

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`.
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

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

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).

Suggested change
"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`.

Copilot uses AI. Check for mistakes.
```

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.
Comment on lines +542 to +549
Copy link

Copilot AI Apr 30, 2026

Choose a reason for hiding this comment

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

“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).

Copilot uses AI. Check for mistakes.

> [!NOTE]
> `recreate-ref` requires `preserve-branch-name: true` to take effect. The agent always starts from the configured base branch — it doesn't literally check out the named branch before making changes.

See [Safe Outputs (Pull Requests)](/gh-aw/reference/safe-outputs-pull-requests/) for full configuration details.

### You use 'agent' and 'agentic workflow' interchangeably. Are they the same thing?

Yes, for the purpose of this technology. An **"agent"** is an agentic workflow in a repository - an AI-powered automation that can reason, make decisions, and take actions. We use **"agentic workflow"** as it's plainer and emphasizes the workflow nature of the automation, but the terms are synonymous in this context.
Expand Down
Loading