github.code.delete_branch

Delete a branch from a GitHub repository

Delete a branch from a GitHub repository.

Inputs:

• owner: Repository owner (required).
• repo: Repository name (required).
• branch_name: Branch to delete (required).
• expected_sha: Current branch tip SHA guard (optional).
• dry_run: Plan without mutating GitHub (optional, default: false).
• default_branch: Known default branch name (optional). Only a hint: a match refuses without a metadata read; a mismatch is verified against GitHub.
• allow_default_branch_delete: Permit deleting the default branch (optional, default: false). Founder/human-only; never set it from a Staff or agent tool binding.

Outputs (terminal state_data):

• status: planned | deleted | not_found
• applied: bool
• branch_name: str
• ref: Full branch ref
• sha: SHA the branch pointed at before deletion

Compensation: Use github.code.create_branch with the captured sha to restore the ref. Plugin required: context.get_plugin("github") must expose a GitHub App installation.

Overview

Property	Value
Workflow type	Atomic
Library	App-github
Version	1.0

Input Schema

Field	Type	Required	Default	Description
owner	string	Yes	—	Repository owner
repo	string	Yes	—	Repository name
branch_name	string	Yes	—	Branch to delete
expected_sha	string	No	—	Expected current branch tip SHA
dry_run	boolean	No	—	Plan without mutating GitHub
default_branch	string	No	—	Known repository default branch (hint; never trusted to allow a delete)
allow_default_branch_delete	boolean	No	—	Allow deleting the default branch. Founder/human-only override, default false. Never set from Staff or agent tool bindings, and never map it from caller input in a composition.

Output Schema

Field	Type	Required	Default	Description
status	string	No	—	—
applied	boolean	No	—	—
dry_run	boolean	No	—	—
branch_name	string	No	—	—
ref	string	No	—	—
sha	string	No	—	—
default_branch	string	No	—	—
allow_default_branch_delete	boolean	No	—	—
expected_sha	string	No	—	—
owner	string	No	—	—
repo	string	No	—	—
failure_reason	string	No	—	—
failure_type	string	No	—	—
failed_action	string	No	—	—
failed_at_state	string	No	—	—
failed_step	string	No	—	—
failed_layer	string	No	—	—
error	string	No	—	—
error_type	string	No	—	—

States

State	Initial	Terminal	Success	Auto-advance	Description
pending	Yes	No	—	execute	—
completed	No	Yes	Yes	—	—
failed	No	Yes	No	—	—

State Diagram

Transitions

From	Action	To	Description
pending	execute	completed	—
* (any state)	fail	failed	—

API Usage

POST /api/workflows/start
Content-Type: application/json

{
  "workflow_type": "github.code.delete_branch",
  "initial_data": {
    "owner": "value",
    "repo": "value",
    "branch_name": "value"
  }
}