Documentation
Product GuideREST API ReferenceMCP Server for AI AgentsWebhooks & EventsIntegrations
WRITE

create_branch

Opens a branch for a work item on GitHub, in a repository connected through the team's App installation, under the workspace's own name or the one given, and links it to the item at once.

Start the work on an item with a branch whose name carries its key, so every push links itself. Give work_item_id; repository_id when the item's project has more than one repository that can take a branch (connected through a live installation that may write its contents), or leave it out when it has exactly one; and name when the workspace's proposal does not suit. The proposal is feature/ or, for a bug, fix/, then the item's key in lower case and a slug of its title cut at a word within forty-eight characters: feature/crm-142-apply-a-voucher-at-checkout. The branch is opened at GitHub from the repository's default branch and answered as the code reference the item now carries, kind branch, state open; code.branch_linked goes out. A name of your own must be one Git accepts, up to two hundred characters of letters, digits, dots, dashes, underscores and slashes with no empty segment, and should keep the key in it, or the pushes to it will link nothing. It needs work-item:update; a client guest's token is refused.

Requires ability

work-item:update

The token behind the MCP session must hold it, or the call is refused with TOKEN_MISSING_ABILITY.

Arguments

work_item_id*string

UUID of the work item the branch is for.

repository_idstringoptional

UUID of the project repository to open it in; optional when exactly one repository can open branches.

namestringoptional

The branch name; the workspace proposes one from the key and the title when left out.

What it returns

{  "data": {    "id": "4d5e6f70-8192-4cad-8e1f-3a4b5c6d7e8f",    "project_id": "7f3d1c92-8b45-4e6a-9d21-5c8e0a4b6f13",    "work_item_id": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",    "reference": "CRM-142",    "work_item_title": "Apply a voucher at checkout",    "repository_id": "9e8d7c6b-5a49-4382-a716-05f4e3d2c1b0",    "repository_full_name": "zuse-technologies/portal",    "kind": "branch",    "external_id": "feature/crm-142-apply-a-voucher-at-checkout",    "ref": "feature/crm-142-apply-a-voucher-at-checkout",    "title": null,    "url": "https://github.com/zuse-technologies/portal/tree/feature/crm-142-apply-a-voucher-at-checkout",    "author": "Nimal Perera",    "state": "open",    "additions": null,    "deletions": null,    "opened_at": "2026-11-03T09:12:00+00:00",    "merged_at": null,    "closed_at": null,    "linked_by": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b",    "created_at": "2026-11-03T09:12:00+00:00",    "updated_at": "2026-11-03T09:12:00+00:00"  }}

How it fails

VALIDATION_FAILED

name is not a branch name Git accepts, a branch of that name exists already, the item's project has several repositories that can take a branch and repository_id was left out, the repository is disconnected, or GitHub refused or did not answer.

INTEGRATION_NOT_CONNECTED

the repository was registered by hand rather than picked from an installation, the installation was forgotten or suspended, or the installation may not write the repository's contents.

RESOURCE_NOT_FOUND

unknown work_item_id, or a repository_id that is not one of the item's project's repositories.

FORBIDDEN

the token is a client guest's, or the holder may not change the project's items.

TOKEN_MISSING_ABILITY

token lacks work-item:update.

Related

list_code_referenceswhether the item has a branch or a pull request already; read it first.list_repositoriesthe project's repositories, to name one when several can take a branch.link_commita commit whose message left the key out.Code references APIthe same door over REST.Git connections APIthe installations the branches open through.

How is this guide?

Last updated on