Jira user story template
Who wants it, what they want and why, then the conditions that make it done. Short enough that people actually fill it in.
The template
[Who] can [do what]
- Priority
- Jira’s default
- Labels
- needs-refinement
Description
User story
As a [type of user], I want [goal] so that [reason].
Acceptance criteria
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]
Context
[Background, links to designs or discussions, and anything already decided.]
Out of scope
- [What this story does not include]
Definition of done
- Acceptance criteria met
- Code reviewed
- Tests added or updated
- Documentation updated, if behavior changed
Show it as Markdown
### User story
As a [type of user], I want [goal] so that [reason].
### Acceptance criteria
- Given [context], when [action], then [result]
- Given [context], when [action], then [result]
### Context
[Background, links to designs or discussions, and anything already decided.]
### Out of scope
- [What this story does not include]
### Definition of done
- [ ] Acceptance criteria met
- [ ] Code reviewed
- [ ] Tests added or updated
- [ ] Documentation updated, if behaviour changed
What a good Jira user story template contains
The story in one sentence: as a type of user, I want a goal, so that a reason. Then acceptance criteria that someone other than the author can check, often written as Given, When, Then. Then context with links, what is out of scope, and a definition of done as a checklist.
The summary says who can do what: “Admins can export the audit log as CSV”. The description holds the rest, so the story still makes sense to someone who missed the refinement meeting.
When to use it
Use it for a change that someone outside the team would notice, small enough to finish in one sprint.
Work nobody outside the team would notice, such as an upgrade or a clean-up, fits the task template better. Something too big for one sprint is an epic, split into stories.
What each section is for
- User story
- The reason after "so that" is the part that most often goes missing, and the part that settles trade-offs later.
- Acceptance criteria
- Each one should be something a tester can check without asking the person who wrote the story.
- Context
- Links rather than copies, so the story does not go out of date.
- Out of scope
- Saying what is not included keeps the story small, and avoids a surprise at review.
- Dependencies Detailed
- Shows a blocked story before the sprint starts, not halfway through it.
- How to test Detailed
- Saves the tester from asking for data or access.
Sections marked Detailed are not in the template above. Switch them on in the generator, where you can also edit the text and the checklist.
Jira user story examples
Four stories from different kinds of product, each written with this template. The acceptance criteria use Given, When, Then, and each one can be checked without asking the author what they meant.
Online shop: keep the basket
- Summary
- Signed-in shoppers keep their basket across devices
- User story
- As a signed-in shopper, I want my basket kept when I leave so that I can finish buying on another device.
- Acceptance criteria
- Given I am signed in with items in my basket, when I sign in on another device, then the same items and quantities are there.
- Given an item in my saved basket has sold out, when I open the basket, then that item is marked unavailable and left out of the total.
- Given I am not signed in, when I come back in the same browser, then my basket is still there.
- Out of scope
- Sharing a basket with someone else
- Keeping a guest’s basket across devices
Business software: export for auditors
- Summary
- Admins can export the audit log as CSV
- User story
- As an account admin, I want to export the audit log as CSV so that I can give it to our auditors without taking screenshots.
- Acceptance criteria
- Given I am an account admin, when I choose Export on the audit log, then a CSV file of the entries shown downloads.
- Given I have filtered the log to a date range, when I export, then the file holds only entries from that range.
- Given I am not an admin, when I open the audit log, then there is no Export button.
- Out of scope
- Scheduled exports
- Formats other than CSV
Internal service: self-service reset
- Summary
- Employees can reset their own VPN token from the portal
- User story
- As an employee locked out of the VPN, I want to reset my token from the service portal so that I do not have to wait for the service desk to open.
- Acceptance criteria
- Given I have confirmed who I am on the portal, when I choose Reset VPN token, then I get a new token and the old one stops working.
- Given the reset fails, when the error appears, then it tells me how to reach the service desk.
- Given a token is reset, when the security team checks the log, then the reset is listed with the time.
- Out of scope
- Hardware tokens
- Resets for contractors without a company account
Mobile app: larger text
- Summary
- Readers can choose a larger text size for articles
- User story
- As a reader with low vision, I want to make article text larger so that I can read without zooming the whole screen.
- Acceptance criteria
- Given I am reading an article, when I choose a larger text size in settings, then the article text uses it and no text is cut off.
- Given I have chosen a size, when I open the app again, then it is still in use.
- Given the phone’s own text size is set larger, when I open the app for the first time, then articles follow it.
- Out of scope
- Menu and button text
Writing acceptance criteria that hold up
- One behavior per criterion. If a line needs “and” twice, split it.
- Describe what the user sees, not how it is built. “A CSV file downloads”, not “the export endpoint returns 200”.
- Include the case that goes wrong: a sold-out item, a failed reset, a user without permission.
- Three to five criteria is usual. Many more often means the story should be split, and an epic may be the better home.
How to make this the starting point in Jira Cloud
Jira Cloud has no issue templates as such. These are the native ways to start every new story from this template, as Atlassian’s own pages describe them, and where each one stops. Our guide to Jira issue templates in Jira Cloud compares them in more detail.
Team-managed projects: a default description for Story
In a team-managed project, each work type can have a default description. Atlassian’s recap on JRACLOUD-4812 gives the path: Project settings → Issue types, select Description, and write the default text. Choose Story and paste the template. It is one text per work type, for the description only, and it cannot contain a table (KB). The label in this template has to be added by hand.
Company-managed projects: Atlassian’s workaround
Here Jira does not support a default for the system Description field. Atlassian’s workaround uses a custom Paragraph field with the template as its default value. That field goes on the Create screen instead of Description, and a post function on the workflow’s Create transition copies it into Description. Plan it with whoever looks after screens and workflows. Stories still get one template.
Cloning a reference story
Keep a story that is never closed, with the template in its description, and copy it with ••• → Clone, as Atlassian’s Clone page describes. The copy is linked to the original and its summary starts with “Clone”. The reference story shows up in searches and on boards, and anyone who can edit it can change the template for everyone.
Automation after the story is created
An Automation rule with the Work item created trigger, a condition on the work type and an Edit work item action can write the template into Description, as in Atlassian’s KB. The person writing the story in the Create dialog still starts from an empty description; the template appears afterwards. Each run counts toward your Automation usage (usage doc).
None of these lets someone pick between story templates in the Create dialog, for example one for a customer-facing feature and one for an internal tool with a different definition of done. That is what an app adds.
Want this as a template people pick in Jira?
Issue Templates & Create Defaults for Jira gives each project a Templates page. Pick a template there and Jira’s own Create dialog opens with the summary, description with its checklist, labels and priority filled in. From version 2.9.0 a template can also set the assignee to the person using it, a due date a number of days ahead, and components. The person can change anything before creating, under Jira’s usual rules for required fields and permissions. Set a default template for a work type, and the Create dialog names it. The app writes nothing into a form by itself. It can also set custom fields (text, number, date, dropdowns and more), and it runs on Jira Cloud only.
To take a template from this page into the app with its formatting, paste it into an issue’s description, then, as a project or Jira administrator, choose Save as template from the issue’s ••• menu.
Questions
What is the format of a user story in Jira?
Jira has no fixed format: a story is a work type with a summary and a description. Most teams write the description as “As a [type of user], I want [goal] so that [reason]”, followed by acceptance criteria and a definition of done.
Should acceptance criteria use Given, When, Then?
It helps when a tester or an automated test will check them, because each criterion states the starting point, the action and the result. A plain list is fine for small stories. What matters is that someone other than the author can tell whether each one is met.
How do I create a user story template in Jira?
In a team-managed project, paste this template into the Story work type’s default description in the project settings. In a company-managed project, use Atlassian’s workaround with a custom Paragraph field and a workflow post function, keep a reference story to clone, or use an app that lets people pick a template.
Where does the definition of done go?
As a checklist at the end of the description, so that it travels with each story and can be ticked off there. If it never changes from story to story, a shared page linked from each story works as well.
Related pages
Or build your own in the Jira issue template generator, and see what Jira Cloud does on its own.
- Jira issue templates in Jira Cloud Default description · Automation · Cloning · Where each one stops
- Jira templates with sub-tasks The same children under every epic or work item, with and without an app
- Bug report template Steps to reproduce · Expected result · Actual result · Environment · How often · Screenshots and logs
- Task template What needs doing · Why · Notes
- Incident template Impact · Started · Current status · Timeline · Workaround
- Spike template Question · Timebox · Why it matters · Output
- Epic template Goal · Problem · Scope · How we will know it worked