switchyard

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

Use Switchyard with Jira

In this guide, you connect Jira to the GitHub repository that your Switchyard project follows, and you start a task that names a Jira work item. At the end, the work item's development panel in Jira shows the commits and the pull request that Switchyard merged for it.

You will have: a Jira work item 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 Jira and holds none of its keys. It writes the work item's key on GitHub, where Jira's GitHub app already looks. Use Switchyard with GitHub Issues says what Switchyard writes and where.

The steps in Jira are Atlassian's own, as Integrate Jira with GitHub and Atlassian's page on naming a work item in your commits and pull requests gave them at the time of writing. When a menu on your screen is different, follow Atlassian's pages: they are the authority.

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

Prerequisites

Step 1 — Install the GitHub for Atlassian app

A Jira site administrator does this step, in Jira.

  1. Select Apps, then Explore more apps.
  2. Search for GitHub for Atlassian, and select it from the results.
  3. Select Get app, then Get it now.

To see that it worked, select Apps, then Manage your apps. The list has GitHub for Atlassian.

The app is in Jira. Next, you connect your GitHub organization to it.

Step 2 — Connect your GitHub organization

An owner of the GitHub organization does this step, in Jira.

  1. Select Get started, then Continue.
  2. Select GitHub Cloud, then Next.
  3. Sign in to GitHub.
  4. Find the organization that owns the repository your Switchyard project follows.
  5. Select Connect, and follow the screens that come after it.

The repository that your project follows must be among the repositories that the app can read. When the app was added to the GitHub organization with Only select repositories, add the repository there.

To see that it worked, select Apps, then Manage your apps, then GitHub for Atlassian in Jira. The page lists the organization.

Jira reads commits and pull requests through this app's own installation on GitHub. There is no webhook for you to add, and Switchyard is not part of it and holds no key of it.

Jira reads the repository. Next, you start a task for a work item.

Step 3 — Start a task with the work item's key

Start the task with the key in capitals, as Jira shows it. Switchyard keeps the key as typed, and Jira links only a key in capitals: jra-123 does not link.

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

MCP: pass issue to yard_workspace_create or yard_workspace_claim.

When the task does only part of the work item, use --part-of JRA-123 (partOf over MCP) instead. Switchyard then writes Part of JRA-123.

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

The task names the work item. Next, you commit and submit.

Step 4 — Commit and submit

Commit with yard commit, which adds Fixes JRA-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 JRA-123

Then submit the task:

yard submit --wait

The merge queue tests the task and merges it on main. Jira links a commit whose message holds the key, and a pull request whose title holds the key. When your project merges through a pull request, because main is protected, Switchyard's landing pull request has the key in its title, with two exceptions: a key given with --part-of is never in the title, and a batch of many tasks whose title would pass 200 characters has no keys in it. Jira links a pull request by its title or its branch's name, not by its description, so in those two cases Jira links the commits and not the pull request. When your project merges with no pull request, the key reaches Jira only in commit messages. In every case, keep the key in the commits: yard commit adds the line, and with plain git commit you write 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 Jira, I will name the work item's key, such as JRA-123.
Start a Switchyard task for it and pass the key in capitals, as I wrote it:
`yard branch new "<goal>" --issue JRA-123`,
or `issue: "JRA-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 work item.
If you commit with plain git, end each commit message with the line `Fixes JRA-123`,
or `Part of JRA-123` when the task is only part of the work item.
Never guess a key that I did not give you.
When I ask for a different piece of work, start a new task for it with its own key.
Do not push it to a task that has merged: the push reopens that task under its old goal.
If your key to Switchyard 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 work item in Jira and look at its development panel. It shows the commits, and the pull request when your project merges through one.

Fixes JRA-123 links in Jira. It does not close. By default, Jira does not change a work item's status because of a commit or a pull request. A status change is Jira's own automation or Smart Commits, which you set up in Jira and which this page does not cover.

What you seeCauseWhat to do
The development panel shows nothing, and the key on GitHub is in small lettersJira links only a key in capitalsSet the key again in capitals: yard tag issue=JRA-123
The development panel shows nothing, and the commits have no line with the keyThe commits were made with plain git commit, which adds nothingEnd each commit message with Fixes JRA-123, or commit with yard commit
The development panel shows nothing, and the key is on GitHub in capitalsThe app cannot read the repository, or the organization is not connectedIn Step 2, connect the organization and add the repository that your project follows
Another work item is linkedThe task names the wrong keySet the right one: yard tag issue=JRA-124. Commits already made keep the line they have
The work item is linked and its status did not changeJira changes no status by defaultChange the status in Jira, or set up Jira's automation

What is not built

Use Switchyard with GitHub Issues has the same list.

Next