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

link_commit

Links a commit to a work item by hand, for a commit whose message left the item's key out; composes the address from the repository and announces the link once.

Link a commit that the repository's webhook could not match. Give work_item_id, repository_id (one of the project's live repositories, read from the Repositories API) and sha (seven characters or the full forty), with message (the commit's first line), url and author when you have them; the address is composed from the repository's own when url is left out, and the state is pushed. The answer is the reference as the item now carries it; code.commit_linked goes out the first time, and linking the same sha again refreshes the title and address rather than doubling the row. A commit whose message already names the key (CRM-142) is linked by the webhook on its own, so use this for the ones that forgot, and put the key in the message next time. 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.

Annotations

Idempotent

Sending the same arguments twice changes nothing the second time.

work_item_id*string

UUID of the work item the commit belongs to.

repository_id*string

UUID of the project repository the commit lives in.

sha*string

The commit sha, seven characters or the full forty.

messagestringoptional

The commit message's first line, up to 500 characters.

urlstringoptional

Where the commit opens; composed from the repository when left out.

authorstringoptional

Who wrote it, as the host names them.

{  "data": {    "id": "3c4d5e6f-7081-4b9c-8d0e-2f3a4b5c6d7e",    "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": "commit",    "external_id": "a1b2c3d",    "ref": "a1b2c3d",    "title": "Apply the voucher at checkout",    "url": "https://github.com/zuse-technologies/portal/commit/a1b2c3d",    "author": "nimal",    "state": "pushed",    "additions": null,    "deletions": null,    "opened_at": "2026-11-02T11:00:00+00:00",    "merged_at": null,    "closed_at": null,    "linked_by": "3f8a1c2e-7b4d-4e5f-9a6b-1c2d3e4f5a6b",    "created_at": "2026-11-02T11:00:00+00:00",    "updated_at": "2026-11-02T11:00:00+00:00"  }}
VALIDATION_FAILED

repository_id or sha missing or malformed (a sha is seven to sixty-four hexadecimal characters), or the repository is disconnected.

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_referenceswhat the item already carries.link_pull_requestthe same for a pull request.list_repositoriesthe project's repositories and their ids.Code references APIthe same link over REST, and the unlink that stays there.

How is this guide?

Last updated on