> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/llms.txt

# Use Switchyard with Linear

In this guide, you connect Linear to the GitHub repository that your Switchyard project follows, and you start a task that names a Linear issue. At the end, the issue in Linear shows the pull request or the commit that Switchyard merged for it, and Linear moves the issue by its own rules.

**You will have:** a Linear issue that links to the work a Switchyard task merged for it.
**Works with:** `yard` and MCP.
**Takes:** about 15 minutes.

Switchyard builds no connection to Linear and holds none of its keys. It writes the issue's id on GitHub, where Linear's GitHub integration already looks. [Use Switchyard with GitHub Issues](/docs/issues) says what Switchyard writes and where.

The steps in Linear are Linear's own, as [Linear's GitHub page](https://linear.app/docs/github) gave them at the time of writing. When a menu on your screen is different, follow Linear's page: it is the authority.

**What Switchyard answers for:** the words it writes on GitHub, which its tests hold exactly. What Linear does with those words is Linear's own GitHub integration at work, which Switchyard does not run.

## Prerequisites

- A Switchyard project that follows a GitHub repository, with `yard` signed in. The [Quickstart](/docs/quickstart) gets you there.
- A Linear account that can change Linear's settings.
- An owner of the GitHub organization, or an administrator of the repository, to install Linear's GitHub integration.
- A Linear issue to work on. This guide uses `ENG-123`.

## Step 1 — Connect Linear to GitHub

Install Linear's GitHub integration on the repository that your project follows.

1. In Linear, open **Settings > Features > Integrations > GitHub**.
2. Click **Enable**.
3. Choose the GitHub organization.
4. Choose **All repositories** or **Only select repositories**. With **Only select repositories**, select the repository that your Switchyard project follows.
5. Click **Install**, and sign in to GitHub when Linear asks.

A GitHub organization owner installs the integration for an organization. A repository administrator can install it for one repository.

To see that it worked, open **Settings > Features > Integrations > GitHub** in Linear again. The page shows the GitHub organization.

Linear reads the repository. Next, you find out how your project merges.

## Step 2 — See how your project merges

Switchyard merges on main in one of two ways, and the way decides whether Step 3 is for you.

- **Through a pull request.** When GitHub protects main with rules that ask for pull requests, approvals or status checks, Switchyard opens a landing pull request for each tested batch. The pull request has the issue's id in its title and a line such as `Fixes ENG-123 (task 8).` in its body. A batch of many tasks whose title would pass 200 characters has no ids in its title, and an id given with `--part-of` is never in the title: the body's line still names each. Linear links by either, and nothing more is needed. Go to Step 4.
- **With no pull request.** Switchyard pushes the tested commits to main. The id reaches Linear only through commit messages. Do Step 3.

To see which it is, look at the repository's pull requests on GitHub. A project that merges through pull requests has pull requests from branches named `switchyard/land/<commit>`. [When main is protected](/docs/connect-github#when-main-is-protected) explains both ways.

You know how your project merges. Next, you turn on commit linking when you need it.

## Step 3 — Turn on commit linking

Do this step when your project merges with no pull request. Linear reads commit messages only when commit linking is on.

1. In Linear's GitHub settings, at the bottom of the page, turn on **Link commits to issues with magic words**. Linear shows a Payload URL and a Secret.
2. On GitHub, open **Settings → Webhooks** of the organization or of the repository.
3. Click **Add webhook**.
4. Enter Linear's Payload URL and Secret, and choose the content type `application/json`.
5. Leave **Push events** selected, and click **Add webhook**.
6. Go back to Linear and click **Done**.

This webhook is between GitHub and Linear. Switchyard is not part of it and holds no secret of it.

To see that it worked, open the webhook on GitHub after the next push to the repository. Its recent deliveries show a push that Linear answered.

Linear reads commit messages. Next, you start a task for an issue.

## Step 4 — Start a task with the issue's id

Start the task with the id as Linear shows it.

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

MCP: pass `issue` to `yard_workspace_create` or `yard_workspace_claim`.

When the task does only part of the issue, use `--part-of ENG-123` (`partOf` over MCP) instead. Switchyard then writes `Part of ENG-123`, which Linear links without moving the issue to Done.

To see that it worked, run `yard status`. It shows the id before the task: `ENG-123 · task 8`.

The task names the issue. Next, you commit and submit.

## Step 5 — Commit and submit

Commit with `yard commit`, which adds `Fixes ENG-123` in a paragraph of its own at the end of the commit message, above the `Change-Id` line. With plain `git commit`, write that line yourself at the end of the message.

`yard commit` knows the id when the task was started with `--issue` in that checkout. When the id was set another way (the board, MCP, or `yard tag` run elsewhere), run `yard status` in the checkout once, and `yard commit` knows it from then on. Only `yard commit` adds the line: other `yard` commands that make commits do not.

```
Round the total once

Fixes ENG-123
```

Then submit the task:

```sh
yard submit --wait
```

The merge queue tests the task and merges it on main. The id is now on GitHub, where Linear reads it.

## Give this to your agent

An agent that has the Switchyard skill already learns this from it. The block is for an agent set up without the skill, or as a reminder in your project's instructions file. Copy it whole.

```
When I give you work from Linear, I will name the issue, such as ENG-123.
Start a Switchyard task for it and pass the id: `yard branch new "<goal>" --issue ENG-123`,
or `issue: "ENG-123"` on yard_workspace_create or yard_workspace_claim.
Use `--part-of` (`partOf`) in place of `--issue` (`issue`) when the task is only part of the issue.
If you commit with plain git, end each commit message with the line `Fixes ENG-123`,
or `Part of ENG-123` when the task is only part of the issue.
Never guess an id that I did not give you.
When I ask for a different piece of work, start a new task for it with its own id.
Do not push it to a task that has merged: the push reopens that task under its old goal.
If your key cannot start a task, tell me and ask for one.
If you work with an agent group key, keep the latest `resume` key of each task, and after you submit,
check your earlier tasks with yard_status: a reviewer may ask for a fix.
```

## Check that it works

After the task merges, open the issue in Linear.

- **Your project merges through a pull request:** the issue shows the landing pull request. By default, Linear moves a linked issue to In Progress when the pull request opens and to Done when it merges.
- **Your project merges with no pull request:** the issue shows the commit. A commit with `Fixes ENG-123` moves the issue to Done when it reaches the default branch.

A team changes what Linear does under **Settings > Team > Workflows & automations > Pull request and commit automations**.

## When it does not link

| What you see | Cause | What to do |
| --- | --- | --- |
| The issue shows nothing, and your project merges with no pull request | Commit linking is off in Linear, or the webhook is missing on GitHub | Do Step 3 |
| The issue shows nothing, and the commits have no `Fixes ENG-123` line | The commits were made with plain `git commit`, which adds nothing | End each commit message with the line, or commit with `yard commit` |
| The issue shows nothing, and the id is on GitHub | Linear's integration cannot read the repository | In Step 1, add the repository that your project follows |
| Another issue is linked | The task names the wrong id | Set the right one: `yard tag issue=ENG-124`. Commits already made keep the line they have |
| The issue is linked and did not move to Done | The task used `--part-of`, or your team changed Linear's automations | Move the issue in Linear, or read the team's automations |
| A person's own pull request shows as closed, not merged | Switchyard closes a person's pull request when its work merges, and first adds the label `externally-merged`, which Linear's page names for merge queues that close pull requests. The label is best effort | Look for the label on the pull request. Without it, move the issue in Linear |

## What is not built

- Switchyard writes no status to Linear. Linear moves the issue by its own rules.
- The board has no link to Linear. 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.

[Use Switchyard with GitHub Issues](/docs/issues#what-is-not-built) has the same list.

## Next

- [Use Switchyard with GitHub Issues](/docs/issues): what Switchyard writes for an issue and where.
- [Pull requests in the merge queue](/docs/pull-requests): put a person's pull request through the merge queue.
- [Working as an agent](/docs/agents): the loop your agent follows.
