Connect Jira
For organisation admins. Connects your Speclr organisation to Jira Cloud once, so project teams can hand stories over to an existing Jira project as epics and stories.
Updated
Use a dedicated machine account
- Clear authorshipEvery epic, story and fix version Speclr creates appears under the account you connect.
- Survives people leavingA personal account takes all hand-overs down with it when its owner leaves.
- Exactly the rights it needsYou grant the account its project permissions once, without widening anyone's own.
Speclr works with Jira Cloud and with existing projects only: it never creates a Jira project. Team-managed and company-managed projects both work.
Create the account and give it access to your Jira site
Create an Atlassian account such as
speclr-bot@acme.comwith a team mailbox. Give it access to Jira on your site and add it to every Jira project your teams will hand stories to.- Two-step verification on, recovery codes stored with the team
- Access to one Atlassian site only, so Speclr connects to the right one
Grant the project permissions
In each Jira project, the account needs these permissions. Company-managed projects grant them through the permission scheme, team-managed projects through the account's role.
- Browse projects
- required
- Create issues
- required
- Edit issues
- required
- Schedule issues
- to rank stories by priority
- Administer projects
- to create fix versions
Make sure the project has an epic level
Speclr files each story under an epic. The project needs an issue type on the epic level of Jira's hierarchy, usually "Epic". Speclr finds it by its level, not by its name, so a renamed epic type works too.
Without one, the project settings warn "This project has no issue type at the epic level. Stories cannot be handed over to it until it has one." A hand-over then stops with "The Jira project needs an issue type at the epic level." before anything is created. The project also needs an issue type for stories.
Connect in Speclr, signed in as the machine account
Open Organisation settings › Integrations › Discover and choose "Connect" on Jira. Only organisation admins see the integrations. When Atlassian asks you to sign in, use the machine account, not your own. A private browser window avoids mix-ups.
Atlassian then shows "Speclr is requesting access to your Atlassian account". Speclr requests the Jira scopes
offline_access read:jira-work write:jira-work read:jira-user manage:jira-project write:issue:jira-software manage:jira-webhook. You only consent; the scopes are set by Speclr.Back in Speclr, the connection appears under Yours and reads "Acts as" the account "on" your site. Check both.
Pick the Jira project in each Speclr project
Any member of a Speclr project can do this. Open Project settings › "Integrations" › "Ticket system" and, under "Work items", "Choose a Jira project…". The list shows the projects the machine account can see.
Speclr checks the project at once: "Write access confirmed · epic level found" means it is ready. "Read only — Speclr needs write access" means the account is missing permissions from step 2.
What Speclr creates in Jira
For each story you hand over:
- An epic per activity. An existing epic with exactly the activity's name is reused.
- A story with that epic as its parent. Its summary starts with the story id, for example
US-014 · Set a spending limit, and is cut at Jira's 255 characters; the full title is in the description. - A label for the step. Jira labels cannot contain spaces, so spaces become underscores:
Set_limit. - A fix version for the milestone, reused by name or created.
- The priority as rank, so the stories appear in Speclr's order.
The activity is the epic, so the step is the only label. Renaming an activity renames its epic, and a story moved to another activity moves to that activity's epic.
In team-managed projects, Jira shows the fix version only when the Releases feature is on (space or project settings › Features › Releases), and the label only when the system field "Labels" is on the Story work type (settings › Work types › Story). Speclr sets both either way. A Jira search such as labels = Set_limit or fixVersion = "MVP" finds them in any case.
The description starts with one info panel: an origin line ("Generated by Speclr · edit in Speclr · exported …"), the specification and the scenarios as code blocks. That panel is Speclr's. Everything below it belongs to your team and is never touched.
If someone edits inside the panel, Speclr does not overwrite it. The story shows "SHOP-2 was edited in Jira.", and your team decides in Speclr: "Keep the Jira version" or "Replace with version N". If the panel itself is broken, for example unwrapped or split, Speclr writes nothing to that description and the run report says "The Speclr panel in the Jira description must be repaired." To repair it, restore the description from the work item's history in Jira; the next update then replaces the panel as usual. Or delete the Speclr text left outside the panel, including the origin line; the story then shows as edited in Jira, and "Replace with version N" puts a fresh panel at the top, with your team's text below it. A work item deleted in Jira shows "SHOP-2 no longer exists."
Status and pull requests
Speclr reads the status of each story and never changes it in Jira. The status category "In Progress" shows as in progress, "Done" as merged. A resolution such as "Won't Do", "Won't Fix", "Declined", "Duplicate", "Cannot Reproduce", "Rejected" or "Obsolete" shows as discarded. Custom statuses count by their category. Team-managed projects often have only the resolution "Done", so "discarded" does not appear there. Speclr checks about every 15 minutes, and sooner when you open a story.
If the Speclr project also has a GitHub repository as its repo target, Speclr links pull requests to the story. It finds them only when the Jira key, such as SCRUM-12, is in the branch name or the pull request title. Otherwise the story list says once, for example: "Pull requests in acme/shop do not name a Jira key such as SHOP-2. Name it in branch names or pull request titles so Speclr can follow them." See Connect GitHub.
Reconnect or disconnect
Reconnect when the connection shows "Nothing is handed over until it is reconnected", as the same machine account. Atlassian also asks for consent again whenever Speclr's scopes change. Another account first names the affected projects.
Disconnecting names them too. Targets and links stay; status turns unknown.
Without some permissions
- Without "Administer projects", the milestone becomes a label, and the run report says so, for example: "The fix version MVP could not be created. The work item carries the label MVP instead."
- Without "Schedule issues", the stories are created but not ordered: "The priority order was not exported."
- Without "Create issues" or "Edit issues", the hand-over stops: "Speclr may not create or edit work items in SHOP. Ask a Jira admin for the permission, or choose another project."
Troubleshooting
- "An admin must reconnect the Jira connection.": reconnect as the machine account, with access to one site only.
- "The Jira project has no issue type for stories.": add one in the project's issue types.
- A Jira project is missing from the list: the account cannot browse it. Add it to the project.
- Pull requests do not show: put the Jira key in the branch name or the pull request title.
- Label or fix version not visible on a work item: turn on Releases and add "Labels" to the Story work type, as described under What Speclr creates in Jira.
