add_vcs_link
Links a task to a pull request, commit, or branch, creating the task↔PR join that PR-driven status automation and shipped-work reports rely on. Only a task ID and GitHub or GitLab URL are required.
Instructions
Link a task to a pull request, commit, or branch. The link is the task↔PR join that PR-driven status automation and 'what shipped for this task?' reports read. Only task_id and url are needed — provider, link_type and external_id are inferred from a GitHub or GitLab URL. The optional status parameter ('merged' or 'closed') records a PR that was already merged or closed before it was linked. Without it the link starts as 'open', and the done-evidence gate blocks move→done on it, since no GitHub webhook fires for a merge that happened before the link existed.
Tool call template
Replace each placeholder with a value matching the input schema. Only required parameters are included; add optional parameters as needed.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"task_id": "<task_id>",
"url": "<url>"
},
"name": "add_vcs_link"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | Yes | Link URL, e.g. https://github.com/owner/repo/pull/123. | |
| role | No | 'review' (the only value) marks the PR as the subject this task reviews or signs off, not the task's own work: its being unmerged no longer blocks move→done. Never set it on the PR that implements the task. To mark a link that already exists, call again with status='open' (or its current status) and role='review'. | |
| title | No | Human-readable label, e.g. the PR title. | |
| ci_sha | No | Commit the CI verdict ran on, 40 hex. | |
| status | No | PR status, if you already know it: open, merged, closed. Pass 'merged' when linking a PR that was merged before this call — that is the one case a webhook can never backfill. Omit it to let the link start as 'open' (the safe default when the PR is still active). Calling add_vcs_link again on the same PR with a status update is safe — it corrects the existing link rather than failing. | |
| task_id | Yes | Task ID. | |
| provider | No | VCS provider: github, gitlab. Inferred from the URL host; defaults to github. | |
| ci_status | No | Delivery state: CI verdict status (pending, running, success, failed, canceled, skipped, manual). Use ci_pipeline_id and ci_sha for the pipeline and commit it ran on. | |
| link_type | No | What the URL points at: pr (alias: pull_request), commit, branch. Inferred from the URL path; defaults to pr. | |
| merged_sha | No | Delivery state: the commit the MR merged as on the target branch, 40 hex. | |
| deployed_at | No | RFC3339 deploy time; defaults to now. | |
| environment | No | Environment of deployed_sha, e.g. prod or staging. | |
| external_id | No | PR number, commit SHA, or branch name. Inferred from the URL; only needed when the URL is not a recognised PR/commit/branch link. | |
| deployed_sha | No | Delivery state: the commit now running in `environment`, 40 hex. Requires environment. The link counts as shipped only when this equals merged_sha on environment=prod. Reporting the same sha and environment again keeps the first deployed_at. | |
| acceptance_by | No | Who accepted. | |
| acceptance_sha | No | Commit the acceptance covered, 40 hex. | |
| ci_pipeline_id | No | Pipeline id of the CI verdict. | |
| acceptance_result | No | Delivery state: live acceptance result, passed or failed — separate from CI and deploy. Add acceptance_by, acceptance_evidence_url and acceptance_sha for who, proof and the commit it covered. | |
| implementation_sha | No | Delivery state (pr links): the commit the change was implemented at, 40 hex. | |
| acceptance_evidence_url | No | Link to the acceptance proof. |