Issue Tracker Guide

Isurus includes a built-in issue tracker for managing bugs, feature requests, and tasks. Every repository has its own issue tracker with support for labels, templates, assignees, pinned issues, cross-references, and automatic closing via commits and pull requests.

Issue States

Every issue is in one of three states:

State	Color	Meaning
New	Blue	Freshly created, not yet reviewed or acknowledged
Open	Green	Acknowledged and/or being actively worked on
Closed	Gray	Resolved, completed, or otherwise done

State transitions:

• All newly created issues start as New.
• An issue automatically transitions from New to Open when:
  • Someone adds the first comment, or
  • The first assignee is added.
• Use the Close button to mark an issue as Closed.
• Use the Reopen button to move a closed issue back to Open.

Creating Issues

1. Navigate to your repository and click the Issues tab.
2. Click New Issue.
3. If templates are available, a template picker appears. Choose from:
   • Bug Report — structured format for reporting bugs.
   • Feature Request — structured format for proposing new features.
   • Blank Issue — start from scratch with an empty description.
4. Enter a title summarizing the issue.
5. Write a description using Markdown (headings, lists, code blocks, links, images, etc.).
6. Click Create Issue.

Issue Templates

Templates pre-fill the description field with a structured format, helping contributors provide consistent, useful information.

Default Templates

Bug Report includes sections for:

• Description of the bug
• Steps to reproduce
• Expected behavior
• Actual behavior
• Environment details

Feature Request includes sections for:

• Description of the feature
• Use case / motivation
• Proposed solution
• Alternatives considered

Managing Templates

Templates can be created at three levels:

Level	Who Can Manage	Availability
Admin (Global)	Site administrators	All repositories across the instance
Organization	Organization owners	All repositories within the organization
Repository	Repository owners	That specific repository only

To manage templates, go to Settings > Issue Templates at the appropriate level (admin panel, organization settings, or repository settings).

Labels

Labels categorize issues so they can be filtered and organized at a glance.

Three-Tier Hierarchy

Labels are defined at three levels and merge together additively:

Level	Scope	Managed In
Admin (Global)	Available to every repository on the instance	Admin Panel > Labels
Organization	Available to all repositories in the organization	Organization Settings > Labels
Repository	Available only to that specific repository	Repository Settings > Labels

When viewing a repository's issues, all three levels are combined into a single flat list. There is no conflict resolution needed — labels from all levels are simply merged.

Label Properties

Each label has:

• Name — a short identifier (e.g., bug, enhancement, priority:high).
• Color — a hex color displayed as a badge (e.g., #d73a4a for red).
• Description — optional text explaining when to use the label.

Applying Labels

On an issue's detail page, use the Labels section in the sidebar to add or remove labels. All available labels (from admin, org, and repo levels) appear in the picker.

Assignees

Assign one or more team members to an issue to indicate who is responsible.

• Add or remove assignees from the issue sidebar.
• Multiple assignees are supported — useful when several people collaborate on a fix.
• Configurable cap — the site administrator sets a default maximum number of assignees. Organization owners can override this up to the admin-configured maximum.
• Auto-open — adding the first assignee to a New issue automatically transitions it to Open.

Pinned Issues

Pin important issues to keep them visible at the top of the issue list, regardless of sort order or filters.

• Pin or unpin an issue from the issue sidebar.
• Configurable cap — administrators control the maximum number of pinned issues per repository.
• Pinned issues always appear at the top of the issue list, above all other issues.

Use pinning for release blockers, important announcements, or long-running tracking issues.

Filtering and Search

The issue list provides several ways to find what you need.

State Pills

Quick-filter tabs across the top of the issue list:

Pill	Shows
Active	All New + Open issues combined
New	Only issues in the New state
Open	Only issues in the Open state
Closed	Only resolved/closed issues

Dropdown Filters

Use the filter dropdowns to narrow results by:

• Label — show only issues with a specific label.
• Author — show only issues created by a specific user.
• Assignee — show only issues assigned to a specific user.

Title Search

Type in the search box to filter issues by title text. The search is applied in combination with any active state pills and dropdown filters.

Sort Options

Sort	Description
Newest	Most recently created first (default)
Oldest	Oldest created first
Recently Updated	Most recently commented or modified first
Most Commented	Highest comment count first

Pagination

Choose a page size of 20, 50, or 100 issues per page. Navigation controls appear at the bottom of the list.

Cross-Referencing

Type #N (where N is an issue number) in any of the following places to create a clickable link to that issue:

• Issue descriptions
• Issue comments
• Commit messages
• Pull request descriptions

For example, writing Related to #42 in a comment creates a link to issue 42. The reference is rendered as a clickable link in all Markdown-rendered text.

Auto-Close via Commits

Include a close keyword followed by an issue reference in your commit message to automatically close an issue when the commit is pushed.

Supported Keywords

All of the following keywords work (case-insensitive):

Keyword	Variants
close	close, closes, closed
fix	fix, fixes, fixed
resolve	resolve, resolves, resolved

Example

hg commit -m "Fix null pointer in auth handler

Fixes #17"

When this commit is pushed to Isurus, issue #17 is automatically closed. The issue's timeline records:

Closed via commit abc1234

You can close multiple issues in a single commit:

hg commit -m "Refactor config loading

Closes #8, fixes #12, resolves #15"

Auto-Close via Pull Request Merge

Include close keywords in a pull request description to automatically close issues when the PR is merged.

Example

When creating a pull request, write in the description:

Implements the new dashboard layout.

Closes #5
Fixes #23

Important: Issues are closed only when the pull request is merged, not when it is created. If the PR is closed without merging, the referenced issues remain open.

The issue's timeline records:

Closed via pull request #42

Reference Keywords

To link to an issue without closing it, use a reference keyword:

Keyword	Variants
ref	ref, refs
reference	reference, references

Example

hg commit -m "Add caching layer for API responses

Refs #30"

This creates a reference link on issue #30's timeline without changing its state:

Referenced by commit def5678

Use reference keywords when a commit or PR is related to an issue but does not fully resolve it.

Issue Timeline

Each issue's detail page displays a chronological timeline combining:

• Comments — user-written discussion entries (Markdown rendered).
• State changes — when the issue was opened, closed, or reopened, and by whom.
• Commit references — commits that mention the issue via #N, close keywords, or reference keywords.
• Pull request references — PRs that mention or close the issue.
• Cross-references — mentions from other issues.

The timeline provides a complete history of an issue from creation to resolution.

Commenting

Any member with access to the repository can add comments to an issue.

• Comments support full Markdown formatting: headings, bold/italic, code blocks, lists, links, and images.
• The first comment on a New issue automatically transitions it to Open, signaling that the issue has been reviewed.
• Use comments to discuss solutions, ask for clarification, or document resolution steps before closing.