Skip to main content

How to Create and Use Issue Templates in Jira (Step-by-Step Tutorial)

· 16 min read
NGPilot
NGPilot
NGPilot

Every team that uses Jira long enough runs into the same problem: inconsistent tickets. One developer files a detailed bug report with reproduction steps, environment details, and screenshots. Another submits a two-line summary with no context. Product managers write user stories that vary wildly in structure, making backlog grooming slower than it needs to be. Support teams log incidents using different formats depending on who is on shift. These inconsistencies compound over time and erode the reliability of your Jira data, making reports unreliable and sprint planning harder than necessary.

Issue templates solve this by standardizing the structure and content of every new ticket. When you create a Jira issue template, every bug report follows the same format, every user story has the same sections, and every task includes the same checklists. The result is faster ticket creation, better reporting, and a shared understanding of what "done" looks like across the team.

This tutorial walks you through the complete process of creating and using issue templates in Jira with Modern Issue Templates for Jira, a Forge-based app that supports rich text formatting, automatic template application, GitHub import, and multi-project sharing. By the end, you will have working templates for bug reports, user stories, and sprint tasks that apply automatically whenever someone creates an issue in your projects.

Why use issue templates in Jira?​

Before diving into the setup, it is worth understanding why issue templates are worth the investment. Teams that adopt templates consistently report four key benefits:

  • Faster ticket creation. Pre-filled fields mean less typing. Instead of starting from a blank screen, team members fill in the sections that matter and skip the boilerplate that the template already provides.
  • Consistent descriptions. Every bug report, feature request, or incident follows the same structure. This makes it dramatically easier for anyone reviewing the backlog to find the information they need without hunting through paragraphs of freeform text.
  • Better reporting. Standardized fields make JQL queries and dashboards more reliable. When every bug has an "Environment" section and every story has "Acceptance criteria," you can build filters and reports that actually work.
  • Faster onboarding. New team members see the expected format immediately. Templates encode institutional knowledge about what a good ticket looks like, so newcomers do not have to guess.

Template types you should create​

Most teams need templates for the following issue types. Each serves a distinct purpose and benefits from a different structure:

  • Bug report template -- captures reproduction steps, expected vs. actual behavior, environment details, and severity assessment. This is the most commonly used template in engineering teams.
  • User story template -- structures feature requests around the problem statement, proposed solution, acceptance criteria, and out-of-scope items. Product managers and designers benefit most from this one.
  • Task template -- standardizes sprint tasks with clear descriptions, subtasks, and completion checklists. Useful for tracking work that supports a larger story or epic.
  • Epic template -- provides a high-level structure for initiatives that span multiple sprints, including goals, key results, affected teams, and milestone dates.
  • Spike template -- frames research and investigation work with a clear question to answer, time-boxed effort, and expected deliverable. Prevents open-ended research tickets that never close.

You do not need to create all of these at once. Start with the one or two issue types your team uses most frequently and expand from there.

Step-by-step: Create and use issue templates in Jira​

Step 1 -- Install Modern Issue Templates for Jira​

Head to the Atlassian Marketplace and search for Modern Issue Templates for Jira. Click Get App and follow the installation prompts. The app runs on Jira Cloud using the Forge platform, which means it installs quickly and does not require any server-side configuration.

If your organization requires admin approval for marketplace apps, send the app link to your Jira administrator and request installation. The process typically takes under a minute once approved.

After installation, access the template manager through the Apps menu in the top navigation of your Jira site. Select Modern Issue Templates from the dropdown. You will see the template management interface -- an empty table if this is your first time using the app, or a list of any existing templates.

Step 2 -- Create your first issue template​

From the template manager, click the Create Template button in the top-right corner. A modal opens with three fields:

  1. Template Name -- a descriptive name that helps you and your team identify the template. Use clear names like "Bug Report" or "User Story -- Product Team" rather than generic labels.
  2. Summary -- the text that will pre-fill the issue summary field when the template is applied. For a bug report, you might use Bug: [brief description]. For a user story, Story: [feature name].
  3. Description -- the rich text content that will pre-fill the issue description. This is where you define the structure, sections, and placeholders that make up the body of the template.

Fill in all three fields and click Save. The template appears in your template table immediately. If you are creating a bug report template, the summary might be Bug: [summary] and the description would contain the structured format we will build in the next step.

Importing templates from GitHub or files​

If your team already has issue templates stored elsewhere, you can skip manual creation and import them directly:

  • From GitHub repository. Click Import Templates, select the From GitHub URL tab, and paste a direct file URL such as https://github.com/username/repo/blob/main/.github/ISSUE_TEMPLATE/bug_report.md. The app fetches the file, extracts YAML frontmatter (name, title, labels), and converts the markdown body to rich text.
  • From GitHub Gist. Select the From GitHub Gist tab and paste a Gist URL. All markdown files in the Gist are imported as separate templates.
  • From file. Select the From File tab and upload a .json or .md file. JSON exports from this app are supported, as are standard markdown files with optional YAML frontmatter.

GitHub import is particularly valuable for engineering teams that already maintain issue templates in their .github/ISSUE_TEMPLATE/ directory. Rather than maintaining two separate sets of templates -- one in GitHub and one in Jira -- you can use the GitHub repository as the single source of truth and re-import whenever templates change.

Step 3 -- Configure template fields and formatting​

The description editor in Modern Issue Templates supports full rich text formatting. Use the toolbar to add structure that guides whoever fills in the ticket:

Formatting options available:

  • Bold, italic, and strikethrough text for emphasis
  • Headings (H1 through H6) to organize sections
  • Bullet lists and numbered lists for steps and checklists
  • Code blocks with syntax highlighting for technical content
  • Links to external resources, internal Confluence pages, or other Jira issues
  • Tables for structured data like environment configurations or test matrices

The goal is to create a template where the structure is obvious and the person creating the issue only needs to fill in the blanks. Well-formatted templates reduce cognitive load and produce better tickets.

Inline editing for quick updates​

You can edit template summaries and descriptions directly in the template table without opening the full editor. Click on any summary cell to make it editable -- press Enter or click outside to save. Click on any description cell to open a compact rich text editor. This is useful for small adjustments like updating a section heading or fixing a typo without navigating to the full editor modal.

Step 4 -- Assign templates to projects and issue types​

Templates only work when they are connected to the projects and issue types where they should apply. To assign a template:

  1. Click the Assign to Project button (the link icon) in the Actions column of the template table.
  2. In the assignment dialog, select one or more projects from the dropdown.
  3. Select the issue types that should use this template (Bug, Story, Task, etc.).
  4. Click Save.

Assigned projects appear as colored badges in the Projects column of the template table. If a template is assigned to more than three projects, you will see a "+N more" indicator.

The recommended approach is to map each issue type to exactly one template per project. For example, in your main engineering project, the Bug issue type maps to the Bug Report template, the Story issue type maps to the User Story template, and the Task issue type maps to the Sprint Task template. This one-to-one mapping keeps things predictable and ensures every new issue gets a template.

Step 5 -- Use templates when creating issues​

Once templates are assigned, the automation kicks in. Here is how it works in practice:

  1. Open the issue creation screen in Jira.
  2. Select the project where your templates are assigned.
  3. Select the issue type (Bug, Story, Task, etc.).
  4. The app detects the matching template and automatically pre-fills the summary and description fields.
  5. Fill in the issue-specific details -- the sections, steps, and information unique to this particular ticket.
  6. Click Create to submit the issue with the full template content.

The template respects any content the user has already entered. If a user starts typing in the description field before the template loads, the template will not overwrite their work. This prevents accidental data loss while still providing the structure for new, blank issues.

When a user changes the issue type after the template has been applied, the app clears the pre-filled content and applies the new template that matches the updated issue type. This ensures the template always matches the selected issue type.

Template examples with field structures​

The following three templates are designed to cover the most common issue types in Jira. You can copy these structures directly into Modern Issue Templates and customize them for your team.

Bug report template​

This is the most widely used template in engineering teams. A well-structured bug report template ensures every defect has enough information for a developer to start investigating without asking clarifying questions.

Template Name: Bug Report Summary: Bug: [brief description of the issue] Description:

## Steps to Reproduce
1.
2.
3.

## Expected Result


## Actual Result


## Environment
- Browser / OS:
- App version:
- Environment (dev / staging / production):

## Severity
- [ ] Critical -- system down or data loss
- [ ] High -- major feature broken
- [ ] Medium -- feature partially broken, workaround available
- [ ] Low -- minor visual or UX issue

## Attachments / Screenshots


## Additional Context

The bug report template captures the essential information a developer needs to reproduce and fix the defect. The "Steps to Reproduce" section uses a numbered list so the reporter can describe the exact sequence of actions. The "Environment" section ensures the developer knows where to look. The severity checklist gives the reporter a structured way to communicate urgency without guessing at a priority level.

User story template​

Product managers and designers benefit from a user story template that frames feature requests around user needs and measurable outcomes.

Template Name: User Story Summary: Story: [feature name] Description:

## User Story
As a [type of user], I want to [action] so that [benefit].

## Problem Statement


## Proposed Solution


## Acceptance Criteria
- [ ]
- [ ]
- [ ]

## Design References


## Out of Scope


## Dependencies

The user story template starts with the classic "As a... I want to... so that..." format, which keeps the focus on user value rather than implementation details. The acceptance criteria checklist is critical because it defines the conditions that must be met for the story to be considered complete. The "Out of Scope" section prevents scope creep by explicitly calling out what this story does not cover.

Sprint task template​

Sprint tasks are the granular work items that support larger stories and epics. A sprint task template ensures each piece of work has a clear description, definition of done, and relevant context.

Template Name: Sprint Task Summary: Task: [brief description] Description:

## Objective


## Parent Story / Epic


## Description


## Subtasks
- [ ]
- [ ]
- [ ]

## Definition of Done
- [ ] Code written and reviewed
- [ ] Unit tests pass
- [ ] Integration tests pass
- [ ] Documentation updated
- [ ] Deployed to staging

## Notes / Context

The sprint task template is designed for individual contributors who pick up work during a sprint. The "Parent Story / Epic" field links the task to its broader context, which is essential for backlog management. The "Definition of Done" checklist provides a standard set of completion criteria that can be customized per team.

Rich text formatting tips for templates​

The quality of your templates depends not just on the structure but on how the content is formatted. Modern Issue Templates provides a full rich text editor, and using it effectively makes your templates easier to fill in and more likely to be adopted.

Use headings to create clear sections. H2 headings for major sections like "Steps to Reproduce" and H3 for subsections. This creates a visual hierarchy that makes the template scannable.

Use checklists for repeatable criteria. Checkboxes (- [ ]) are supported in the editor and give reporters a clear, interactive way to mark off items. Use them for acceptance criteria, definition of done, severity assessment, and any other yes/no decisions.

Use code blocks for technical content. If your template includes API payloads, SQL queries, or configuration snippets, wrap them in code blocks with the appropriate language tag for syntax highlighting. This makes the template content more readable and signals to the reporter where technical details should go.

Keep placeholder text obvious. Use brackets like [brief description] or [type of user] to mark fields that the reporter needs to fill in. This distinguishes template instructions from permanent content and makes it clear what needs to be replaced.

Use tables for structured comparisons. If your template includes environment details or test matrices, use tables to present the information in a compact, organized format.

GitHub import for engineering teams​

For teams that already maintain issue templates in GitHub, the import feature eliminates duplicate work. Here is how to make the most of it:

  1. Store templates in your repository. Keep templates in .github/ISSUE_TEMPLATE/ alongside your code. This makes them reviewable through pull requests and version-controlled just like any other file in the repository.

  2. Use YAML frontmatter. GitHub issue templates support YAML frontmatter at the top of the file. The app extracts the name field as the template name, the title field as the summary template, and the labels field for metadata. The body of the markdown file becomes the template description.

  3. Import and assign. After importing, assign the templates to your Jira projects and issue types. The imported templates work exactly like manually created ones -- they support auto-apply rules, inline editing, and export.

  4. Re-import when templates change. When your team updates a template in GitHub (after a pull request review), re-import it to update the Jira version. The app handles duplicate names by appending a number suffix, so you can rename the updated version and delete the old one.

Best practices for managing templates​

Start with one project​

Rolling out templates to every project simultaneously is tempting but risky. Differences in team workflows, custom fields, and issue type schemes mean that a template that works perfectly in one project may need adjustments in another. Start with your most active project or the team that has the strongest need for consistency. Validate the templates and auto-apply rules in that context, gather feedback, and iterate before expanding.

Map every issue type to a template​

Do not leave any issue type without a corresponding template. If you have Bug, Story, Task, Epic, and Spike issue types, you should have at least five templates. When a team member creates an issue and no template applies, that is a gap in your system. Configure auto-apply rules for every issue type in every project where templates are active.

Review templates quarterly​

Templates are not set-and-forget. As your team's processes evolve, your templates should evolve with them. Schedule a quarterly review where a project manager or team lead examines each active template and asks whether the format still matches the team's current workflow. Have new fields become important? Have some sections become unnecessary? Update the templates to reflect the current reality.

Export templates as backups​

Use the export feature to download your templates as a JSON file. This serves as a backup in case of accidental deletion and makes it easy to share template configurations between Jira instances. Select the templates you want to export using the checkboxes in the template table and click Export Selected. The file is named templates-export-{timestamp}.json.

Clone templates for variations​

If you need a slightly different version of an existing template (for example, a bug report template for mobile vs. web), use the Clone action to create a copy and modify it. This is faster than creating a new template from scratch and ensures consistency across variations.

Troubleshooting common issues​

Template not applying automatically​

Check three things: (1) Is the template assigned to the correct project? (2) Is the template assigned to the correct issue type? (3) Has the user already entered content in the description field? Templates only apply to blank fields to prevent overwriting user input.

Import fails from GitHub​

Common causes include 404 errors (the file URL is incorrect or the file does not exist), 403 errors (the repository is private or requires authentication), and rate limiting (GitHub API has rate limits; wait a few minutes and try again). Make sure you are using a direct file URL, not a directory URL.

Formatting lost after import​

Markdown conversion preserves most formatting, but some complex HTML in markdown files may not convert perfectly. After importing, open the template in the editor and adjust any formatting that did not translate correctly. The rich text editor makes this quick.

What to do next​

Now that you have issue templates configured for your Jira projects, here are the logical next steps to get even more value from your template system:

  • Expand coverage. Create templates for any remaining issue types that do not yet have one. Epics, spikes, and sub-tasks are common gaps.
  • Share across projects. Use the Assign to Project feature to roll your validated templates out to additional projects.
  • Automate with Jira Automation. Combine Modern Issue Templates with Jira's built-in automation rules to create workflows that trigger on template-applied issues.
  • Gather feedback. After your team has used the templates for a sprint or two, collect feedback on what works and what does not. Templates improve with iteration.

For the complete feature documentation, visit the Modern Issue Templates for Jira user guide.