Issue Tracking

Comprehensive issue tracking system with labels, milestones, assignments, and project management features

Overview

Gitea’s issue tracking system provides a complete solution for managing bugs, feature requests, tasks, and discussions. With support for labels, milestones, assignments, and rich markdown content, teams can effectively organize and track their work.

Creating Issues

1. Navigate to Issues

   Go to the repository and click on the Issues tab in the navigation menu.

2. Click New Issue

   Click the New Issue button to open the issue creation form.

3. Fill in Details

   • Title: Concise description of the issue
   • Description: Detailed information with markdown support
   • Labels: Categorize the issue (bug, enhancement, etc.)
   • Milestone: Associate with a project milestone
   • Assignees: Assign team members
   • Projects: Link to project boards
4. Submit

   Click Create Issue to submit. The issue receives a unique number identifier.

Issue Creation from Code

// From services/issue/issue.go
func NewIssue(ctx context.Context, repo *repo_model.Repository, 
             issue *issues_model.Issue, labelIDs []int64, 
             uuids []string, assigneeIDs []int64, 
             projectID int64) error {
    if err := issue.LoadPoster(ctx); err != nil {
        return err
    }
    
    // Create issue with transaction
    if err := db.WithTx(ctx, func(ctx context.Context) error {
        if err := issues_model.NewIssue(ctx, repo, issue, 
                                       labelIDs, uuids); err != nil {
            return err
        }
        
        // Add assignees
        for _, assigneeID := range assigneeIDs {
            if _, err := AddAssigneeIfNotAssigned(ctx, issue, 
                issue.Poster, assigneeID, true); err != nil {
                return err
            }
        }
        
        // Link to project
        if projectID > 0 {
            if err := issues_model.IssueAssignOrRemoveProject(ctx, 
                issue, issue.Poster, projectID, 0); err != nil {
                return err
            }
        }
        return nil
    }); err != nil {
        return err
    }
    
    // Send notifications
    notify_service.NewIssue(ctx, issue, mentions)
    return nil
}

Issue Templates

Standardize issue creation with predefined templates:

Markdown Templates

Create issue templates in .gitea/ISSUE_TEMPLATE/ or .github/ISSUE_TEMPLATE/:

---
name: Bug Report
about: Report a bug to help us improve
labels: bug
---

## Bug Description
A clear description of the bug.

## Steps to Reproduce
1. Go to '...'
2. Click on '...'
3. See error

## Expected Behavior
What you expected to happen.

## Actual Behavior
What actually happened.

## Environment
- OS: [e.g., Ubuntu 22.04]
- Browser: [e.g., Chrome 120]
- Version: [e.g., 1.21.0]

YAML Templates

Create structured forms with YAML:

name: Feature Request
about: Suggest an idea for this project
labels:
  - enhancement
body:
  - type: textarea
    id: description
    attributes:
      label: Feature Description
      description: Describe the feature you'd like to see
      placeholder: A clear and concise description
    validations:
      required: true
  
  - type: dropdown
    id: priority
    attributes:
      label: Priority
      options:
        - Low
        - Medium
        - High
        - Critical
    validations:
      required: true

Labels

Categorize and filter issues with labels:

Creating and Managing Labels

Label Properties

• Name: Label identifier
• Description: Purpose of the label
• Color: Visual identification (hex color)
• Exclusive: Only one label from group

Default Labels

• bug: Something isn’t working
• enhancement: New feature or request
• documentation: Documentation improvements
• duplicate: Duplicate issue
• wontfix: Will not be worked on

// From models/issues/label.go
type Label struct {
    ID          int64
    RepoID      int64
    OrgID       int64
    Name        string
    Description string
    Color       string // Hex color code
    NumIssues   int
    NumClosedIssues int
    IsExclusive bool   // Only one label from this group
    Scope       string // For scoped/exclusive labels
}

Scoped Labels

Create exclusive label groups using the format scope/item:

Scoped Label Examples

Priority Labels (exclusive)

• priority/low
• priority/medium
• priority/high
• priority/critical

Status Labels (exclusive)

• status/needs-triage
• status/in-progress
• status/blocked
• status/ready-for-review

Component Labels (non-exclusive)

• component/api
• component/ui
• component/database
• component/auth

When a scoped label is applied, any existing label with the same scope is automatically removed.

Milestones

Organize issues into release cycles or project phases:

Creating Milestones

1. Navigate to Milestones

   Go to Issues → Milestones in the repository

2. Create Milestone

   Click New Milestone and provide:

   • Title: Milestone name (e.g., “v1.0.0”, “Q4 2025”)
   • Description: Goals and scope
   • Due Date: Target completion date (optional)
3. Track Progress

   • View open/closed issue counts
   • Monitor completion percentage
   • Filter issues by milestone
   • Close milestone when complete

Milestone Management

// Milestones track groups of issues
type Milestone struct {
    ID              int64
    RepoID          int64
    Name            string
    Content         string  // Description
    RenderedContent string
    IsClosed        bool
    NumIssues       int
    NumClosedIssues int
    Completeness    int  // Percentage complete
    DeadlineUnix    timeutil.TimeStamp
    ClosedDateUnix  timeutil.TimeStamp
}

Milestone completion percentage is automatically calculated based on open vs. closed issues.

Assignments

Assign issues to team members for accountability:

Assigning Issues

Web Interface

Single Assignment

1. Open the issue
2. Click Assignees in the sidebar
3. Select one or more assignees
4. Click outside to save

Bulk Assignment

1. Select multiple issues with checkboxes
2. Click Actions dropdown
3. Choose Assign to…
4. Select assignee(s)

Via Comments

Use slash commands in issue comments:

/assign @username
/unassign @username
/assign me

Issue Comments

Collaborate through threaded discussions:

Comment Features

Rich Content

• Full markdown support
• Code blocks with syntax highlighting
• Image and file attachments
• Emoji reactions
• @mentions for notifications

Actions

• Edit comment history
• Delete comments
• Quote reply
• React with emoji
• Mark as resolved

Slash Commands

Perform actions directly from comments:

/close - Close the issue
/reopen - Reopen the issue
/assign @user - Assign to user
/unassign @user - Remove assignment
/label bug - Add label
/unlabel bug - Remove label
/milestone v1.0 - Set milestone
/lock - Lock conversation
/unlock - Unlock conversation

Issue References

Link related issues and pull requests:

Reference Syntax

Same Repository

#123 - Reference issue/PR #123
Fixes #123 - Auto-close when merged
Closes #123 - Auto-close when merged
Resolves #123 - Auto-close when merged

Cross-Repository

user/repo#123 - Reference issue in another repo
Fixes user/repo#123 - Auto-close external issue

Commit References

abc123def - Reference commit SHA
user/repo@abc123def - Reference commit in another repo

Dependencies

Track issue dependencies to manage blockers:

1. Add Dependency

   In the issue sidebar, use Dependencies section to add blocking or blocked-by issues

2. View Dependency Graph

   See visual representation of issue dependencies in the issue view

3. Resolve Dependencies

   Dependencies are automatically updated when blocking issues are closed

Time Tracking

Track time spent on issues:

Estimate Time

Set time estimates for planning:

• Add estimated time in issue
• Use format: 2h, 30m, 1d 4h
• Update estimates as needed

Track Time

Record actual time spent:

• Start/stop timer in issue
• Manually add time entries
• View total time spent
• Compare estimate vs. actual

Issue Filtering and Search

Filter Options

Available Filters

Status

• Open issues
• Closed issues
• All issues

Author

• Created by specific user
• Created by you

Assignee

• Assigned to user
• Assigned to you
• No assignee

Labels

• Has specific label(s)
• Has no labels
• Label combinations (AND/OR)

Milestone

• In specific milestone
• No milestone

Sort

• Newest first
• Oldest first
• Most commented
• Recently updated
• Least recently updated

Search Syntax

# Search issue titles and content
is:issue memory leak

# Combine filters
is:open is:issue label:bug assignee:@me

# Search by author
author:username is:issue

# Search in milestone
milestone:v1.0 is:open

# Date ranges
created:>2025-01-01
updated:<2025-03-01

Issue Notifications

Automatic Notifications

• Issue creation
• Assignment changes
• Mentions (@username)
• Comment replies
• Status changes

Subscription Management

• Watch repository (all issues)
• Subscribe to specific issues
• Unsubscribe from issues
• Configure notification preferences

Issue Locking

Lock conversations to prevent further comments:

Locked issues can still be reopened, closed, or modified by users with write access. Only commenting is restricted.

Closing Issues

Manual Closure

• Click Close button in issue view
• Add closing comment explaining resolution
• Use /close slash command in comment

Automatic Closure

Issues are automatically closed when pull requests with closing keywords are merged:

Fixes #123
Closes #456
Resolves #789

Best Practices

Issue Management Tips

Writing Good Issues

• Use clear, descriptive titles
• Include reproduction steps for bugs
• Add relevant context and screenshots
• Use templates for consistency

Organization

• Apply labels immediately
• Set milestones for release planning
• Assign owners for accountability
• Use projects for kanban-style tracking

Workflow

• Triage new issues regularly
• Keep issue count manageable
• Close duplicates and outdated issues
• Link related issues and PRs

Communication

• Be respectful and constructive
• Update progress in comments
• Use reactions instead of “+1” comments
• Reference commits and PRs

See Also

• Pull Requests - Code review workflow
• Projects - Kanban boards for issue tracking
• Repositories - Repository management