Issues

Issues are the primary tool for tracking work: bug reports, feature requests, discussions. Each issue belongs to a repository and can contain descriptions, labels, milestones, assignees, and checklists.

Creating an Issue

1. Open the Issues tab in the repository
2. Click “New Issue”
3. Fill in:
   • Title - brief description (required)
   • Description - details in Markdown (optional)
   • Assignee - who will work on it
   • Labels - categorization (bug, feature, documentation)
   • Milestone - which release/stage it belongs to
   • Project - which Kanban board to display on
4. Click “Create”

Cross-references

In descriptions and comments, you can reference other issues:

• #42 - link to an issue in the current repository
• group/repo#42 - link to an issue in another repository
• Closes #42 or Fixes #42 in a pull request description - the issue will close automatically on merge

Checklists

Create checklists inside issue descriptions:

- [ ] Write tests
- [ ] Update documentation
- [x] Fix the bug

Checklist progress is shown in the issue list.

---

Issue Templates

Ensure users create issues in a consistent format by adding templates.

Creating Templates

Create files in the .gitriver/templates/issue/ directory:

<!-- .gitriver/templates/issue/bug-report.md -->
---
name: Bug Report
about: Report a bug
labels: ["bug"]
---

## Bug Description
Briefly describe the issue.

## Steps to Reproduce
1. Go to ...
2. Click ...
3. See ...

## Expected Behavior
What should have happened.

## Actual Behavior
What actually happened.

## Environment
- GitRiver version:
- Browser:
- OS:

When creating an issue, users see a list of templates to choose from.

---

Labels

Labels are colored tags for categorizing issues.

Built-in Labels

Label	Color	Purpose
bug	red	Bug report
enhancement	blue	Feature request
documentation	green	Documentation
question	yellow	Question
duplicate	gray	Duplicate
wontfix	gray	Won’t fix
good first issue	purple	For newcomers

Managing Labels

Repository Settings -> Labels:

• Create new (name, color, description)
• Edit existing
• Delete (label is removed from all issues)

Filtering

In the issues list, use filters:

• By one or multiple labels
• By assignee
• By author
• By milestone
• By state (open / closed)
• Free text search

---

Milestones

Milestones group issues by stages or releases.

Creating a Milestone

1. Open the Milestones tab in the repository
2. Click “New Milestone”
3. Specify:
   • Title (e.g., v1.2.0)
   • Description - what’s included
   • Due date (optional)

Progress

Each milestone shows:

• Progress bar - percentage of closed issues
• Open / closed issue count
• Days until deadline (if set)

---

Kanban Boards (Projects)

Visual issue management through Kanban boards.

Creating a Project

1. Open the Projects tab in the repository (or group)
2. Click “New Project”
3. Specify name and description
4. Default columns are created:
   • To Do
   • In Progress
   • Done

Customizing Columns

• Add new columns (e.g., “In Review”, “Testing”)
• Rename existing ones
• Reorder by dragging
• Delete empty columns

Working with Cards

• Drag and drop - move issues between columns
• Add issues - click ”+” in a column and select an issue
• Auto-move - issues move to “Done” when closed
• Filtering - by labels, assignees, priority

Group-level Projects

Projects can be created for an entire group - allowing issues from any repository in the group. Useful for cross-team initiatives.

---

Comments

Formatting

Comments support full Markdown:

• Text, lists, tables
• Syntax-highlighted code blocks
• Images (drag & drop or paste from clipboard)
• Math formulas (KaTeX)
• Diagrams (Mermaid)

Mentions

• @username - mention a user (they receive a notification)
• @group/team - mention a team
• #42 - link to an issue

Reactions

Add emoji reactions to comments instead of +1 comments.

Editing and Deleting

Comment authors and administrators can edit and delete comments. Edit history is preserved.

---

Automation

Auto-closing Issues

If a pull request description or commit contains keywords:

Closes #42
Fixes #42
Resolves #42

The issue closes automatically when the pull request is merged.

Notifications

Issue participants (author, assignee, subscribers) receive notifications for:

• New comment
• Status change
• Assignee change
• @ mention

Notification channels are configured in user profile settings.