Link tickets

Build parent and child trees, mark blockers, relate and mark duplicates, and attach GitHub commits and pull requests to a ticket.

Written for
user
Roles
owner, admin, member, project-manager, elevated-client-user
Requires
Anyone who may edit the ticket you link from, and who can see the target ticket
Feature
tickets

Tickets can be linked to each other in four ways: as parent and child, as blocker and blocked, as related, and as duplicates. SAQ has no separate epic, milestone, or subtask objects: a parent ticket is the epic or milestone, and its children are the work under it. A ticket can also carry references to GitHub commits and pull requests.

Before you start

You need to be able to edit the ticket you link from (Owner or Admin, a member of its project, or any workspace user on an Inbox ticket) and to see the ticket you link to. Regular client users cannot link tickets.

Steps

  1. Open the ticket. The Links group in the Details rail lists Parent, Children, Blocks, Blocked by, Relates to, and Duplicates, each row only when it has entries.
  2. Under the list, choose the Link type (Relates to, Blocks, Duplicates, or Parent), type the other ticket's id under Ticket id (for example ACME-12), and select Link.
  3. To remove a link, select the cross next to it (Remove link). A parent is removed from the child's page; the children list on the parent is read-only.

To link GitHub, paste a commit or pull request address into the GitHub URL field under the Links group and select Link GitHub.

Rules

  • Parent and child. A ticket has at most one parent and any number of children. Setting a parent from ticket A to ticket B makes A a child of B. A ticket cannot be its own parent or ancestor, and a chain of parents is limited to 10 levels, counting the moved subtree. Closed linked tickets are shown struck through.
  • Estimates roll up. A ticket with children has no estimate of its own; its Estimate row shows the sum of the estimates of the children you may see, marked "(sum of children)". Reports grouped by ticket roll time up through visible ancestors as well. See Estimate.
  • Blocks and blocked by. "A blocks B" appears as Blocks on A and Blocked by on B. Dependency cycles are refused, and a chain of blockers is limited to 10 links.
  • Relates to and duplicates. Symmetric links with no rules beyond not linking a ticket to itself. Marking a duplicate does not close or merge anything; close the duplicate yourself if that is what you mean.
  • One link per pair and type. Linking the same two tickets the same way twice does nothing.
  • Visibility. Links to tickets you cannot see are hidden entirely: no title, no id, no count. The link exists and other people see it. A parent you cannot see is not shown on the child either.
  • Timeline. Adding or removing a link is recorded on both tickets ("added a link (Blocks)"); setting a parent is recorded on the child.
  • Links travel. Moving a ticket to another project keeps every link. Deleting a ticket removes its links; its children stay and lose their parent.
  • GitHub links are references only. SAQ stores the repository, commit SHA or pull request number, and the address you pasted. It never contacts GitHub, fetches nothing, and has no GitHub app or webhook. The link shows as owner/repo @ 1a2b3c4 or owner/repo #42. An Owner or Admin sees every link in the workspace under Settings → Channels → GitHub. See GitHub links.

Examples

Planning a release: create a ticket "Release 3.2" with kind Planning, then open each work ticket and set Parent to ACME-200. "Release 3.2" shows the children and the sum of their estimates.

A bug cannot be fixed before an upgrade: open the upgrade ticket, choose Blocks, enter the bug's id, and select Link. The bug then shows the upgrade under Blocked by; there is no separate "Blocked by" link type to choose.

Through the API: POST /api/w/acme/tickets/ACME-184/links with {"targetId": "01924c3e-6b2a-7d11-9d0e-3a1f4b5c6d7e", "kind": "blocks"}; PUT /api/w/acme/tickets/ACME-184/parent with {"parentId": null} clears the parent. The MCP tool link_tickets accepts ticket ids such as ACME-184 directly. See the API reference.

Common problems

  • "There is no ticket at this address that you can see." The id you typed does not exist or you may not see that ticket.
  • "A ticket cannot link to itself." / "A ticket cannot be its own parent." Check the id.
  • "That would make the ticket its own ancestor." The parent you chose is already below this ticket in the tree.
  • "The parent chain would be too long." / "The dependency chain would be too long." The limit is 10 levels or links; flatten the structure.
  • "That link would create a dependency cycle." The target already blocks this ticket, directly or through other tickets.
  • "Paste an https://github.com/…/commit/… or …/pull/… URL." Only commit and pull request addresses on github.com are accepted; the repository in the address must match, the SHA must be 7–40 hex characters, and the pull request number must be positive.
  • "A parent ticket has no estimate of its own; it is the sum of its children." Set estimates on the children.
  • Update a ticket Edit a ticket's title, description, kind, priority, labels, dates, estimate, and assignee from the ticket page, and who may change each field.
  • GitHub links How a ticket stores a reference to a GitHub commit or pull request, the validation rules, and the fact that SAQ never contacts GitHub.
  • Ticket link Ticket links relate tickets to each other as parent and child, blocks, relates to, or duplicates, and point a ticket at a GitHub commit or pull request.
  • Estimate An estimate is the planned effort on a leaf ticket in minutes; a parent ticket shows the sum of the children the viewer may see.
  • Viewers, links, and GitHub Share tickets with viewers, set parent and child relations, add blocks, relates, and duplicates links, and store GitHub references through the SAQ REST API.