Skip to main content

Modern Issue Templates for Jira - User Guide

Introduction​

Modern Issue Templates for Jira is a powerful Forge app that helps Jira administrators create, manage, and automatically apply issue templates across projects. With support for rich text formatting, multi-source imports (JSON, Markdown, GitHub), and automatic template application, you can standardize issue creation and improve team productivity.

Getting Started​

Accessing the Template Manager​

  1. Navigate to your Jira site
  2. Click on the Apps menu in the top navigation
  3. Select Modern Issue Templates from the dropdown
  4. You'll see the template management interface with a table of all your templates

Understanding the Interface​

The template manager displays your templates in a table with the following columns:

  • Checkbox: Select templates for bulk export
  • Name: The template's display name
  • Summary: The template text for the issue summary field (editable inline)
  • Description: A preview of the template description (editable inline)
  • Projects: Project keys where this template is assigned
  • Actions: Quick action buttons (Edit, Clone, Delete, Assign)

Creating Templates​

Method 1: Create from Scratch​

  1. Click the Create Template button in the top-right corner
  2. Fill in the template details:
    • Template Name: A descriptive name for your template
    • Summary: The text that will pre-fill the issue summary field
    • Description: Rich text content for the issue description
  3. Use the rich text editor toolbar to format your description:
    • Bold, italic, strikethrough text
    • Headings (H1-H6)
    • Bullet and numbered lists
    • Code blocks with syntax highlighting
    • Links and more
  4. Click Save to create the template

Method 2: Import from File​

You can import templates from JSON or Markdown files:

  1. Click the Import Templates button
  2. Select the From File tab
  3. Click Choose File and select your .json or .md file
  4. The app will parse the file and create templates automatically
  5. Templates with duplicate names will be renamed with a number suffix (e.g., "Bug Report (2)")

Supported Formats:

  • JSON: Export files from this app or custom JSON with template structure
  • Markdown: Standard markdown files with optional YAML frontmatter

Method 3: Import from GitHub​

Import templates directly from GitHub repositories or Gists:

From GitHub Repository​

  1. Click Import Templates
  2. Select the From GitHub URL tab
  3. Paste a GitHub file URL, for example: 
    https://github.com/username/repo/blob/main/.github/ISSUE_TEMPLATE/bug_report.md
  4. Click Fetch to import the template

From GitHub Gist​

  1. Click Import Templates
  2. Select the From GitHub Gist tab
  3. Paste a Gist URL, for example: 
    https://gist.github.com/username/abc123def456
  4. Click Fetch to import all markdown files from the Gist

GitHub Template Features:

  • Automatically extracts YAML frontmatter metadata
  • Converts markdown formatting to rich text
  • Supports GitHub issue template format
  • Handles multiple files in a single Gist

Editing Templates​

Quick Inline Editing​

For fast updates, you can edit templates directly in the table:

Edit Summary​

  1. Click on any summary cell in the table
  2. The text becomes editable
  3. Make your changes
  4. Press Enter or click outside to save

Edit Description​

  1. Click on any description cell in the table
  2. A rich text editor appears
  3. Make your formatting changes using the toolbar
  4. Click outside the editor to save

Full Template Editor​

For comprehensive edits:

  1. Click the Edit button (pencil icon) in the Actions column
  2. The template modal opens with all fields
  3. Edit the name, summary, and description
  4. Click Save to apply changes

The modal closes immediately while saving happens in the background for a smooth experience.

Managing Templates​

Clone a Template​

To create a copy of an existing template:

  1. Click the Clone button (copy icon) in the Actions column
  2. A duplicate template is created with "(Copy)" appended to the name
  3. Edit the cloned template as needed

Delete a Template​

To remove a template:

  1. Click the Delete button (trash icon) in the Actions column
  2. Confirm the deletion in the dialog
  3. The template is permanently removed

Select All Templates​

Use the checkbox in the table header to quickly select or deselect all templates for bulk operations.

Assigning Templates to Projects​

Templates must be assigned to projects and issue types to work automatically.

Assign a Template​

  1. Click the Assign to Project button (link icon) in the Actions column
  2. In the assignment dialog:
    • Select Projects: Choose one or more projects from the dropdown
    • Select Issue Types: Choose which issue types should use this template
  3. Click Save

View Assignments​

Assigned projects appear as colored badges in the Projects column. If a template is assigned to more than 3 projects, you'll see "+N more" indicator.

How Assignment Works​

When a user creates an issue:

  • The app checks the selected project and issue type
  • If a matching template exists, it automatically pre-fills the summary and description
  • Users can still edit the pre-filled content before creating the issue

Exporting Templates​

Export Selected Templates​

  1. Select templates using the checkboxes in the first column
  2. The Export Selected (N) button appears showing the count
  3. Click the button to download a JSON file
  4. The file is named templates-export-{timestamp}.json
  5. Use this file to back up templates or share with other Jira instances

Markdown and Formatting​

Markdown Support​

When importing markdown files, the app converts markdown syntax to rich text:

  • **bold** → bold text
  • *italic* → italic text
  • ~~strikethrough~~ → strikethrough text
  • `code` → inline code
  • # Heading → Heading levels 1-6
  • - item or * item → Bullet lists
  • 1. item → Numbered lists
  • ```code``` → Code blocks with syntax highlighting
  • [text](url) → Clickable links
  • > quote → Blockquotes

YAML Frontmatter​

GitHub issue templates often include YAML frontmatter at the top:

---
name: Bug Report
title: "Bug: "
labels: ["bug"]
assignees: ["maintainer"]
---

## Description
Describe the bug...

The app automatically extracts:

  • name → Template name
  • title → Summary template
  • labels → Mapped to issue types when possible
  • assignees → Stored as metadata

HTML Comments​

HTML comments (<!-- -->) and &nbsp; entities are automatically stripped during import to ensure clean template content.

Automatic Template Application​

How It Works​

Once templates are assigned to projects and issue types:

  1. User opens the issue creation screen
  2. Selects a project and issue type
  3. The app automatically finds a matching template
  4. Summary and description fields are pre-filled
  5. User can edit the content before creating the issue

When Templates Apply​

Templates apply when:

  • A matching project and issue type combination exists
  • The user hasn't manually entered content yet
  • The issue type is changed (clears fields and applies new template)

When Templates Don't Apply​

Templates won't apply if:

  • No matching template exists for the project/issue type
  • The user has already entered custom content
  • The template is not assigned to any projects

Tips and Best Practices​

Template Naming​

  • Use clear, descriptive names like "Bug Report" or "Feature Request"
  • Avoid special characters that might cause issues
  • Keep names concise for better table display

Summary Templates​

  • Keep summaries short and focused
  • Use placeholders like Bug: [describe issue] to guide users
  • Avoid overly long summary templates

Description Templates​

  • Use headings to structure the template
  • Include clear instructions for each section
  • Use bullet points for checklists
  • Add code blocks for technical templates
  • Keep formatting simple and readable

Project Assignment​

  • Assign templates to specific projects for better organization
  • Use different templates for different issue types
  • Review and update assignments regularly

Import Best Practices​

  • Test imports with a single file first
  • Review imported templates before assigning to projects
  • Use GitHub imports to leverage community templates
  • Export templates regularly as backups

Troubleshooting​

Template Not Applying Automatically​

Check:

  • Is the template assigned to the correct project?
  • Is the template assigned to the correct issue type?
  • Have you deployed the latest version of the app?

Import Fails from GitHub​

Common Issues:

  • 404 Error: Check the URL is correct and the file exists
  • 403 Error: The repository might be private or require authentication
  • Rate Limiting: GitHub API has rate limits; wait a few minutes and try again
  • Invalid URL: Ensure you're using a direct file URL, not a directory

Formatting Lost After Import​

  • Markdown conversion preserves most formatting
  • Some complex HTML in markdown may not convert perfectly
  • Edit the template after import to adjust formatting

Duplicate Template Names​

  • The app automatically adds (2), (3), etc. to duplicate names
  • Rename templates after import if needed
  • Use unique names when creating templates manually

Advanced Features​

Batch Operations​

  • Select multiple templates with checkboxes
  • Export selected templates in one operation
  • Use select all checkbox for bulk selection

Template Versioning​

  • Export templates before making major changes
  • Keep backup JSON files of important templates
  • Clone templates to create variations

GitHub Integration​

  • Import community templates from public repositories
  • Share your templates via GitHub Gists
  • Keep templates in version control alongside your code

Support and Feedback​

If you encounter issues or have suggestions:

  1. Check this guide for troubleshooting steps
  2. Review the app logs in Forge CLI if you're a developer
  3. Contact your Jira administrator for assistance
  4. Report bugs or request features through your organization's support channels

Version: 1.0 Last Updated: March 2026