Issue Tracking

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

Navigate to Issues

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

Click New Issue

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

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

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
YAML 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]

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

Navigate to Milestones

Go to Issues → Milestones in the repository

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)

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
Via Comments

Single Assignment

Open the issue
Click Assignees in the sidebar
Select one or more assignees
Click outside to save

Bulk Assignment

Select multiple issues with checkboxes
Click Actions dropdown
Choose Assign to…
Select assignee(s)

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
Cross-Repository
Commit References

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

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

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

Dependencies

Track issue dependencies to manage blockers:

Add Dependency

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

View Dependency Graph

See visual representation of issue dependencies in the issue view

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

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

Getting Started

Core Features

Administration

User Management

Integrations

​Overview

​Creating Issues

​Issue Creation from Code

​Issue Templates

​Labels

​Creating and Managing Labels

Label Properties

Default Labels

​Scoped Labels

​Milestones

​Creating Milestones

​Milestone Management

​Assignments

​Assigning Issues

​Issue Comments

​Comment Features

Rich Content

Actions

​Slash Commands

​Issue References

​Reference Syntax

​Dependencies

​Time Tracking

Estimate Time

Track Time

​Issue Filtering and Search

​Filter Options

​Search Syntax

​Issue Notifications

Automatic Notifications

Subscription Management

​Issue Locking

​Closing Issues

​Manual Closure

​Automatic Closure

​Best Practices

​See Also

Build docs developers (and LLMs) love

Overview

Creating Issues

Issue Creation from Code

Issue Templates

Labels

Creating and Managing Labels

Scoped Labels

Milestones

Creating Milestones

Milestone Management

Assignments

Assigning Issues

Issue Comments

Comment Features

Slash Commands

Issue References

Reference Syntax

Dependencies

Time Tracking

Issue Filtering and Search

Filter Options

Search Syntax

Issue Notifications

Issue Locking

Closing Issues

Manual Closure

Automatic Closure

Best Practices

See Also