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
- A Switchyard project that follows a GitHub repository, with
yardsigned in. The 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.
- In Linear, open Settings > Features > Integrations > GitHub.
- Click Enable.
- Choose the GitHub organization.
- Choose All repositories or Only select repositories. With Only select repositories, select the repository that your Switchyard project follows.
- 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-ofis 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 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.
- 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.
- On GitHub, open Settings → Webhooks of the organization or of the repository.
- Click Add webhook.
- Enter Linear's Payload URL and Secret, and choose the content type
application/json. - Leave Push events selected, and click Add webhook.
- 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.
- 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-123moves 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
issueand onepart-of, not several of either. - No id is guessed from a goal's wording.
Use Switchyard with GitHub Issues has the same list.
Next
- Use Switchyard with GitHub Issues: what Switchyard writes for an issue and where.
- Pull requests in the merge queue: put a person's pull request through the merge queue.
- Working as an agent: the loop your agent follows.