merge_branch

Merge a head branch into a base branch through an existing approved pull request. If the merge would cause conflicts, returns a human-readable diff showing the conflicting changes so you can resolve them manually. Requires Owner role and the same distinct-collaborator approval policy as merge_pull_request. An Owner cannot bypass review by choosing this route. Provides view: pr-workflow (ui://apps/pr-workflow) renders this tool’s result when MCP Apps are available.

Parameters

Name	Type	Required	Default	Description
model_name	Annotated[str, Field(description='Name of the Bridge Town model.')]	Yes	—
head_branch	Annotated[str, Field(description='Name of the branch to merge into base_branch.')]	Yes	—
base_branch	Annotated[str, Field(description="Target branch to merge into. Defaults to 'main'.")]	No	'main'
commit_message	Annotated[str, Field(description='Custom commit message for the merge. If omitted, a default is generated.')]	No	''
expected_head_sha	Annotated[str, Field(description='Optional expected SHA of head_branch tip for optimistic concurrency. Fails if the branch has moved since you last read it.')]	No	''
dry_run	Annotated[bool, Field(description='When true, validate the merge without committing. Returns conflict status without modifying any branch.')]	No	False
break_glass_reason	Annotated[str, Field(description='Required justification only when the captured policy permits a human-owner break-glass direct merge. Ignored for normal approved-PR merges.')]	No	''
workspace_id	`Annotated[str	None, Field(description=WORKSPACE_ID_FIELD_DESCRIPTION)]`	No	None

Returns

Returns a structured object. Top-level fields:

• model (string)
• head_branch (string)
• base_branch (string)
• merged (boolean)
• conflict (boolean)
• up_to_date (boolean)
• message (string)
• approval_rule (string)
• approvers (array<object>)
• policy_version (integer)
• break_glass (boolean)

See the response example below for the full payload shape.

Example

Tool Call

{
  "name": "merge_branch",
  "arguments": {
    "model_name": "forecasts",
    "head_branch": "scenario/aggressive-growth",
    "base_branch": "main",
    "commit_message": "Merge aggressive-growth scenario"
  }
}

Response

{
  "model": "forecasts",
  "head_branch": "scenario/aggressive-growth",
  "base_branch": "main",
  "merged": true,
  "conflict": false,
  "up_to_date": false,
  "message": "Successfully merged 'scenario/aggressive-growth' into 'main'.",
  "approval_rule": "merge-policy:legacy:v0",
  "approvers": [
    {
      "kind": "human",
      "display_name": "Human collaborator"
    }
  ],
  "policy_version": 0,
  "break_glass": false
}

Notes

• Module: Branches
• Requires an authenticated Bridge Town session (OAuth) or an API token.