switchyard

for agents: this page is markdown at https://switchyard.so/docs/issues.md; every page is listed in llms.txt.

Use Switchyard with GitHub Issues

Name the issue that a task serves, so that the issue's id is on GitHub where GitHub Issues, or your tracker's own GitHub integration, looks for it. This page has the steps for GitHub Issues and the facts that every tracker shares.

You will have: a task that names its issue, and the words Fixes <id> or Part of <id> on GitHub when the task's work lands. Works with: yard and MCP (yard_workspace_create, yard_workspace_claim).

Switchyard builds no connection to your tracker and holds none of its keys. It writes the issue's id where Linear's, Jira's and GitHub's own GitHub integrations already look.

For Linear or Jira, follow that tracker's guide: Use Switchyard with Linear or Use Switchyard with Jira.

Before you start

Step 1 — Name the issue when the task starts

Type the id as your tracker shows it, such as ENG-123, JRA-7 or #123. Switchyard keeps the id as typed, and Jira links a key only when it is in capitals.

yard branch new "<goal>" --issue ENG-123

When the task is only part of the issue, name the issue with --part-of instead:

yard branch new "<goal>" --part-of ENG-123

A task has at most one --issue, the issue it completes, and at most one --part-of, an issue it is part of. One issue can take several tasks.

In a shell, quote a GitHub issue number, so that the shell does not read it as a comment: --issue '#123'.

MCP: pass issue, or partOf, to yard_workspace_create or yard_workspace_claim.

The task names its issue. Next, you change the id if it was wrong.

Step 2 — Change the issue later

Set the tag issue on the task:

yard tag issue=ENG-124

Without a task's name, yard tag changes the task of the checkout you are in. yard tag task-3 issue=ENG-124 names the task.

The task names the new issue. Next, the id goes into the task's commits.

Step 3 — Put the id in the commits

Switchyard writes Fixes <id> for the issue a task completes, and Part of <id> for an issue it is part of.

Round the total once

Fixes ENG-123

The commits carry the id. Next, the task's work lands on GitHub.

Step 4 — Submit the task

Submit the task as usual. Where the id reaches GitHub depends on how the project merges:

The project mergesThe id is in
through a pull request, because main is protectedthe landing pull request's title, such as Land task 8 (ENG-123) and task 9, and a line of its body, such as Fixes ENG-123 (task 8).; and the commit messages
with no pull requestthe commit messages only

When the project merges with no pull request, the id reaches GitHub only through commit messages. A task whose commits do not carry the line then shows nothing to your tracker.

What your tracker then does

Each tracker acts on those words by its own rules. This is that tool's behaviour, which its own documentation describes, and Switchyard does not control it.

A person's own pull request

A person's pull request that goes through the merge queue is closed by Switchyard when its work merges, as Pull requests in the merge queue explains. Before it closes the pull request, Switchyard adds the label externally-merged to it, so that Linear counts it as merged. GitHub creates the label in the repository the first time.

The label is best effort: when it cannot be added, the pull request is still closed, and its work is still merged.

Verify

Run yard status. It shows the id before the task (ENG-123 · task 8), and the board shows the id before the task's name: ENG-123 · task 8 · codex for @ada. On the task's page the id links to every active task that names the same issue.

After the task merges, open the issue in your tracker and look for the pull request or the commit.

What is not built

Next