github.refs.delete_ref

Delete a branch or tag Git ref from a GitHub repository

Delete a branch or tag Git ref from a GitHub repository.

Inputs:

• owner: Repository owner (required).
• repo: Repository name (required).
• ref: Full Git ref, e.g. refs/heads/feature/x or refs/tags/v1.0.0 (required).
• expected_sha: Current ref 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
• ref: Full deleted/planned ref
• sha: SHA the ref pointed at before deletion

Compensation: This workflow is the cleanup counterpart for ref-creating workflows. 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
ref	string	Yes	—	Full Git ref, e.g. refs/heads/feature/x or refs/tags/v1.0.0
expected_sha	string	No	—	Expected current ref 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	—	—
ref	string	No	—	—
ref_type	string	No	—	—
ref_name	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.refs.delete_ref",
  "initial_data": {
    "owner": "value",
    "repo": "value",
    "ref": "value"
  }
}