> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/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](/docs/linear) or [Use Switchyard with Jira](/docs/jira).

## Before you start

- The project follows a GitHub repository, as [Connect a GitHub repository](/docs/connect-github) explains.
- For GitHub Issues, the issue is in the repository that the project follows. Nothing else is set up.

## 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.

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

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

```sh
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:

```sh
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.

- **`yard commit`** adds the words in a paragraph of their own at the end of the commit message, above the `Change-Id` line, unless the message already names the id. It knows the id when the task was started with `--issue` in that checkout, or after `yard status` or `yard tag` has run there. No other `yard` command that makes commits adds them.
- **Plain `git commit`** adds nothing. The agent, or you, writes the line at the end of the commit message. The [agents' skill](/docs/agents) tells an agent to do so.

```
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 merges | The id is in |
| --- | --- |
| through a pull request, because [main is protected](/docs/connect-github#when-main-is-protected) | the 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 request | the 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.

- **GitHub** closes an issue of the same repository when `Fixes #123` merges into the default branch. See [Linking a pull request to an issue](https://docs.github.com/en/issues/tracking-your-work-with-issues/using-issues/linking-a-pull-request-to-an-issue).
- **Linear** links a pull request by the id in its title, and a commit once commit linking is turned on in Linear. [Use Switchyard with Linear](/docs/linear) has the steps.
- **Jira** links a commit or a pull request that holds the key in capitals. [Use Switchyard with Jira](/docs/jira) has the steps.

## 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](/docs/pull-requests) 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

- Switchyard writes no status back to the tracker. The tracker changes the issue by its own rules.
- The board has no link to the tracker. On a task's page the id links to the board's other tasks that name it.
- A task names one `issue` and one `part-of`, not several of either.
- No id is guessed from a goal's wording. A task with no `--issue` and no `--part-of` names no issue, even when its goal mentions one.

## Next

- [Pull requests in the merge queue](/docs/pull-requests): put a person's pull request through the merge queue.
- [Connect a GitHub repository](/docs/connect-github#when-main-is-protected): when the merge queue merges through a pull request.
- [Working as an agent](/docs/agents): what an agent does with an issue's id.
