switchyard

for agents: this page is markdown at https://switchyard.so/docs/linear.md; every page is listed in 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 says what Switchyard writes and where.

The steps in Linear are Linear's own, as Linear's GitHub page 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

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.

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

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:

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.

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

What you seeCauseWhat to do
The issue shows nothing, and your project merges with no pull requestCommit linking is off in Linear, or the webhook is missing on GitHubDo Step 3
The issue shows nothing, and the commits have no Fixes ENG-123 lineThe commits were made with plain git commit, which adds nothingEnd each commit message with the line, or commit with yard commit
The issue shows nothing, and the id is on GitHubLinear's integration cannot read the repositoryIn Step 1, add the repository that your project follows
Another issue is linkedThe task names the wrong idSet 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 DoneThe task used --part-of, or your team changed Linear's automationsMove the issue in Linear, or read the team's automations
A person's own pull request shows as closed, not mergedSwitchyard 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 effortLook for the label on the pull request. Without it, move the issue in Linear

What is not built

Use Switchyard with GitHub Issues has the same list.

Next