Jira

With Jira as a workspace’s issue tracker, Limn links each pull request to the Jira tickets it names, reads those tickets, and uses them in the story check, the ticket view, This Sprint and the AI review’s open points. Limn reads Jira with a token you save in Settings. It writes to Jira in exactly three places, and only when you press the button.

#What you need

• Your Jira site’s address, for example https://acme.atlassian.net.
• On Jira Cloud: your Atlassian account email and an API token. Create the token at id.atlassian.com → Security → API tokens.
• On Jira Data Center or Server: a personal access token, made from your Jira profile. Leave the email empty.

The token acts as you. It needs to be able to browse the projects whose tickets you want Limn to read. To change a status from Limn, it also needs permission to transition those issues; to assign one, permission to assign them; to update a ticket’s text, permission to edit them.

#Set it up

1. Open Settings → Integrations. Under Issue tracker, set Provider to Jira.
2. Type the Base URL.
3. Type your Project keys, comma-separated, for example PAY, OPS. Only keys with these prefixes count as tickets. This Sprint also uses them to find the open sprint.
4. Choose Where to look: PR title and branch name (default) or PR title only.
5. Under Jira API access (optional), type your Email (Cloud only) and API token, and press Check connection.
6. Save. Limn starts reading the tickets of open pull requests in the background.

#How pull requests link to tickets

• Limn looks for keys like PAY-142 in the pull request title and, with project keys set, in the branch name. Commit messages are never read.
• Without project keys, Limn looks in the title only, and is careful about things that look like keys but are not.
• You can add a ticket by hand from a pull request’s Story check: open Add tickets and paste the ticket’s link or key. Board links and issue links both work. See Story checks.

#Choose the ticket fields

Jira sites often have several fields called “Acceptance Criteria”, and each issue type can use a different one. Once Limn has read some tickets, Ticket fields under the Issue tracker section is a table: one row per issue type, with a Criteria column and an Open points column:

• Criteria: the field that holds the acceptance criteria. Limn picks uses the field whose name best matches “Acceptance Criteria”.
• Open points: where the ticket’s undecided points are. Limn picks uses a field named like “Open points”, else an “Open points” section of the description. Description only reads just that section.

A change applies at once to every stored ticket of that type in the workspace. Until any ticket is read, the list says “No Jira tickets read yet.”

#What Limn reads

• For each ticket a pull request names: the title, description, acceptance criteria, issue type, status, assignee, the tickets it is blocked by, the created and resolved dates, and the comments.
• For This Sprint: the open sprint’s tickets in your projects, with their text and dates.
• The tickets that sprint tickets link to or mention, even outside the sprint, so the critical path can show what the sprint waits on.

How often Limn reads

Opening a page in Limn never calls Jira, so pages stay fast and your Jira rate limit is spent only on background reads. Saving the tracker settings starts a read at once. If Jira refuses the token, Limn pauses reading for that workspace for 30 minutes rather than retry again and again; saving a new token ends the pause at once.

#What Limn writes

Limn writes to Jira in exactly three places. Each happens only when you press, and none is ever retried.

Change a status

In a ticket’s story view, the status chip is a menu. Opening it asks Jira which statuses the ticket can move to; picking one makes that transition at once. Limn lists only transitions it can make without Jira’s own form.

Assign a ticket

In a ticket’s story view, the assignee is a menu. Opening it lists the people Jira lets you assign in the ticket’s project, and Unassigned. Picking one assigns the ticket at once.

Update the ticket

When you plan a build with Implement story, the plan can include a draft update to the ticket’s description and criteria. You can edit it, then press Update ticket; Limn asks once before it replaces the text in Jira. Update ticket writes the description and the acceptance criteria field, in that field’s own format, or the criteria section of the description when the ticket keeps them there. When you change only the criteria in the description, Limn replaces only that section and leaves the rest of the description exactly as it is in Jira. A criteria field that Jira does not let Limn edit, or that is not a text field, is left as it is, and Limn says so.

#Troubleshooting

Confluence pages on the same Atlassian site can use this Jira connection. See Confluence. Where the token is kept is in Data and storage.