> Switchyard docs. Every page, as markdown, is listed at https://switchyard.so/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](/docs/issues) says what Switchyard writes and where.

The steps in Jira are Atlassian's own, as [Integrate Jira with GitHub](https://support.atlassian.com/jira-cloud-administration/docs/integrate-with-github/) and [Atlassian's page on naming a work item in your commits and pull requests](https://support.atlassian.com/jira-software-cloud/docs/reference-issues-in-your-development-work/) 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

- A Switchyard project that follows a GitHub repository, with `yard` signed in. The [Quickstart](/docs/quickstart) gets you there.
- A Jira site administrator, to install the app.
- An owner of the GitHub organization, to connect it. Only an owner sees the **Connect** button.
- A Jira work item to work on. Jira's keys look like `JRA-123`, and this guide uses that one.

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

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

```sh
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](/docs/connect-github#when-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.

## When it does not link

| What you see | Cause | What to do |
| --- | --- | --- |
| The development panel shows nothing, and the key on GitHub is in small letters | Jira links only a key in capitals | Set the key again in capitals: `yard tag issue=JRA-123` |
| The development panel shows nothing, and the commits have no line with the key | The commits were made with plain `git commit`, which adds nothing | End each commit message with `Fixes JRA-123`, or commit with `yard commit` |
| The development panel shows nothing, and the key is on GitHub in capitals | The app cannot read the repository, or the organization is not connected | In Step 2, connect the organization and add the repository that your project follows |
| Another work item is linked | The task names the wrong key | Set 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 change | Jira changes no status by default | Change the status in Jira, or set up Jira's automation |

## What is not built

- Switchyard writes no status to Jira.
- The board has no link to Jira. On a task's page the key links to the board's other tasks that name it.
- A task names one `issue` and one `part-of`, not several of either.
- No key 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.
