# Connect Jira

> Monitor Jira with the JQL you already write. New matches, status changes, comments, SLAs near a breach and sprint scope reach an island on your Mac, from Jira Cloud or Data Center.

Source: https://coisland.app/docs/connect-jira/

## What you need

- **You need:** API token (Cloud) or personal access token (Data Center), from id.atlassian.com › Security › API tokens (https://id.atlassian.com/manage-profile/security/api-tokens)
- **The form asks:** Jira site, Connector name, Email, API token
- **You can watch:** Issues, Status changes, Comments, SLAs, Sprint scope
- **Access:** JQL searches only

To connect Jira to CoIsland you need your site's address and a token: an API token plus your email on Jira Cloud, a personal access token on Jira Data Center. CoIsland calls your site's REST API straight from your Mac, with no CoIsland server or account in between, and keeps the token in your login Keychain. This page covers both tokens, the connector form, the five Jira monitor kinds with JQL you can paste, and the errors you may meet.

## Jira Cloud or Data Center: what you need

- **Jira Cloud:** your site, such as `https://your-team.atlassian.net`, the email of your Atlassian account, and an API token. CoIsland signs in with basic authentication, email and token.
- **Jira Data Center:** your server's address with its context path, if any, such as `https://jira.example.com/jira`, and a personal access token from your Jira profile. No email: CoIsland sends the token as `Authorization: Bearer`.

The email tells the two apart: with one, the connector signs in as Jira Cloud; without one, as Data Center. A site ending in `.atlassian.net` or `.jira.com` must have an email, and **Test connector** checks what the site says it is.

## Create a Jira API token (Jira Cloud)

1. Sign in at [id.atlassian.com › Security › API tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
2. Select **Create API token**, not **Create API token with scopes**.
3. Name it after what it is for, such as `CoIsland`.
4. Pick an expiry date, from 1 to 365 days away.
5. Select **Create**, then copy the token.

Why no scopes: Atlassian's scoped tokens are called through `api.atlassian.com/ex/jira/{cloudId}`, while CoIsland calls your site's own address, so it needs a token without scopes. Since December 15, 2024, Atlassian gives new API tokens a one-year expiry by default, and a token lasts at most a year. When yours expires, checks fail with the token message listed in [Troubleshooting](#troubleshooting-jira-connector-errors).

## Create a personal access token (Jira Data Center)

Personal access tokens exist in Jira Software and Jira Core 8.14 and later, and in Jira Service Management 4.15 and later.

1. In Jira, select your avatar at the top right, then **Profile**.
2. Select **Personal access tokens** in the left-hand menu, then **Create token**.
3. Give it a name, such as `CoIsland`.
4. Optionally, set it to expire after a number of days.
5. Select **Create** and copy the token: Jira does not show it again once you select **Close**.

The token carries your own permission level. Jira marks it **Expires soon** five days before it expires, and an expired token cannot be reactivated. Your administrator can cap a token's lifetime, 365 days by default.

## Connect Jira in CoIsland

Open **Settings › Connectors**, click **+** at the top right (or **Add Connector** when you have none yet), and choose **Jira**.

*Screenshot: Add a connector: pick the Jira card. It covers SLAs and sprint scope too, not only issues, status changes and comments.*

The form has two groups, **Site** and **Access**:

| Field | What to enter |
|---|---|
| Jira site | The address you open Jira at, with `https://`: the token is never sent unencrypted. On Cloud a pasted board link works; on Data Center, keep the context path. |
| Connector name | What monitors call it, filled in from the site until you type your own: `your-team` for `your-team.atlassian.net`. Letters, digits, `_` and `-`. |
| Email | Jira Cloud only: the Atlassian account the token belongs to. |
| API token | The token you created, either kind. |

Then click **Test connector**, which saves nothing. It asks the site's `/rest/api/2/serverInfo` without the token, to learn whether it is Cloud or Data Center, then calls `/rest/api/2/myself` with it. A success reads **Connected**, with your name, your email or user name, the edition and the host.

Click **Add Connector**. The site, the deployment and the email go to `~/Library/Application Support/CoIsland/connectors.json`, the token to your login Keychain. The first Jira connector becomes the default, which monitors use unless they name another. Add one connector per site if you have several.

*Screenshot: Settings › Connectors: the Jira connector acme on acme.atlassian.net is the default for Jira, Ready, and used by one monitor.*

## Choose what to watch: the five Jira monitor kinds

Open **Monitors**, add a monitor and choose **Jira**. Every kind takes one JQL query and alerts on what enters it, with **Runs on** (the connector), **Alert when** (new items appear, or a count crosses a threshold), **Check every** (15 minutes by default, from 30 seconds to 30 days) and **Sound**. A new-items monitor's first check records what already matches and raises nothing; a count monitor already past its threshold alerts on its first check.

*Screenshot: New Jira monitor: the five kinds on top, then examples with their JQL, each a click from the editor.*

### Issues

An issue alerts when it starts matching. It is tracked by its ID, so a move to another project does not make it new.

```sql
project = OPS AND issuetype = Bug
  AND priority in (Highest, High)
  AND statusCategory != Done
```

### Status changes

An issue alerts each time it is in a status it was not in at the last check, with the status it came from. A change dated more than an hour before the previous check does not alert: the issue came back into your JQL, it did not move. Keep the window longer than the check interval.

```sql
project = OPS
  AND status CHANGED TO Done AFTER "-1d"
```

### Comments

Each new comment on the issues your JQL picks alerts, with its author and text. Jira Cloud's search sends each issue's 20 newest comments, so when more than 20 arrive on one issue between two checks, only the newest 20 alert.

```sql
watcher = currentUser()
  AND updated >= "-2d"
```

### SLAs (Jira Service Management)

A request alerts when it starts matching. Use Jira Service Management's SLA functions, with the SLA's name as your service project shows it: `breached()` for a goal already missed, `remaining()` for one about to be.

```sql
project = HELP
  AND "Time to resolution" = breached()
```

`remaining()` also returns requests already breached, so exclude them, as Atlassian suggests:

```sql
project = HELP
  AND "Time to resolution" < remaining("30m")
  AND "Time to resolution" != breached()
```

### Sprint scope (Jira Software)

An issue alerts when it joins a sprint that was started and not yet completed, with the sprint's name. It needs Jira Software's Sprint field.

```sql
project = APP
  AND sprint in openSprints()
```

Click **Test** to run the JQL once: nothing is saved or alerted. A check reads up to 1,000 issues (10,000 for Issues, SLAs and Sprint scope on Data Center); when more match, nothing is compared and the monitor asks you to narrow the query.

*Screenshot: An Issues monitor: the JQL box with its hint, the High-priority bugs and Assigned to me examples, Test, then Alert when, Sound and the schedule.*

When a monitor fires, the island opens for a few seconds with its sound. The alert shows each issue with its key, summary, status and assignee, and you can hand it to [an agent](https://coisland.app/docs/agents/).

## Permissions the Jira account needs

- **Browse projects** on every project your JQL searches. Jira returns only the issues the account can see, so a missing permission shows as fewer issues, not an error.
- **Agent access** to the service project for SLA monitors: Atlassian notes that only Jira Service Management agents can view SLA metrics.
- **Jira Software** on the site for sprint monitors.

Both tokens act as your account, with all its permissions: neither is read-only by itself. CoIsland only reads with yours: it searches and looks up issues, and its one POST asks Jira's JQL parser to check a query. To limit what the connector sees, use an account that can browse only the projects you want watched.

## What a Jira monitor's watch file looks like

Every monitor is a `.sql` file in `~/.coisland/watches`, Jira ones included. The `-- kind:` line names the Jira kind, and the body is the JQL, sent to Jira as written; the header never is. A file with no kind is Snowflake SQL. Saved with the acme connector picked under **Runs on** and a request line set under **Advanced**, the SLA example above becomes this file:

```sql
-- name: Breached resolution time
-- kind: jira.sla
-- connector: acme
-- every: 15m
-- alert: new-rows
-- title: {KEY} {SUMMARY}
-- sound: Glass

project = HELP
  AND "Time to resolution" = breached()
```

The kinds are `jira.issues`, `jira.status`, `jira.comments`, `jira.sla` and `jira.sprint`. Without a `connector` line, the monitor runs on the default Jira connector. `title` sets how an issue reads in the island, with columns such as `{KEY}`, `{SUMMARY}`, `{STATUS}` and `{ASSIGNEE}`. Changing the JQL, the kind or the connector starts a new baseline. [Watch files](https://coisland.app/docs/watch-files/) lists every header key.

## Troubleshooting Jira connector errors

CoIsland shows these on the connector form, under **Test**, or on the monitor.

- **The token was refused. Check it has not expired or been revoked.** Jira answered 401, or answered as a signed-out user, which CoIsland refuses so a monitor never shrinks silently. On Cloud, check the email is the token's owner. For a new token, add a new connector and pick it under **Runs on**.
- **Not allowed. The token may lack a permission.** Jira answered 403. Check the account's project permissions.
- **jira.example.com does not answer as a Jira site.** The address answered with a page, nothing, or a redirect. CoIsland never follows redirects: enter the address Jira ends up at, with the context path on Data Center.
- **This is a Jira Cloud site: enter the email of the Atlassian account the token belongs to.** Fill in **Email**.
- **This is a Data Center site: leave Email empty, it signs in with a personal access token.** Clear **Email**.
- **Jira refused the query:** then Jira's reason. Fix the JQL in Jira's advanced search, then paste it back.
- **Jira says:** then a reason, as a warning. On Cloud, a misspelled field or project returns no issues instead of an error, so CoIsland asks Jira's strict JQL parser whenever a search comes back empty.
- **This site has no Sprint field: sprint monitors need Jira Software.** Use another kind.
- **The saved settings of acme are incomplete. Add it again.** Its site, deployment or email in `connectors.json` is missing, often after a hand edit. Add it under a new name (names are unique) and point its monitors at it.
- **No Jira connector is named acme.** A monitor's `-- connector:` line names a connector that does not exist.
- **More than the 1000 rows fetched match, so nothing is compared. Narrow the query.** Tighten the JQL, with a project or a date.

## Common questions

### How do I create a Jira API token for CoIsland?

At id.atlassian.com, open **Security › API tokens**, select **Create API token**, name it, pick an expiry of up to 365 days, and copy it into the connector form with your Atlassian email.

### Should I use a Jira API token with scopes?

No. Atlassian's scoped tokens are called through `api.atlassian.com`, and CoIsland calls your site's own address. Use **Create API token**, without scopes.

### Can I connect Jira Data Center with a personal access token?

Yes. Create it under your avatar › **Profile** › **Personal access tokens**, enter your server's address with its context path, and leave **Email** empty.

### Does CoIsland need Jira admin rights?

No. The account needs to browse the projects your JQL searches, plus agent access for SLA monitors.

### Can CoIsland change my Jira issues?

No. It only reads. The token stays in your login Keychain and goes only to your Jira site, never to a CoIsland server.

### How do I get Jira alerts on my Mac without email?

Connect Jira, then add a monitor: the island opens for a few seconds with a sound when it fires. The [Jira notifications guide](https://coisland.app/guides/jira-notifications-mac/) walks through it.

Next: [Getting started](https://coisland.app/docs/getting-started/) for the rest of the app, or the [Jira connector](https://coisland.app/jira/) for everything it can watch.