> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/go-gitea/gitea/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

<Steps>
  <Step title="Navigate to Issues">
    Go to the repository and click on the **Issues** tab in the navigation menu.
  </Step>

  <Step title="Click New Issue">
    Click the **New Issue** button to open the issue creation form.
  </Step>

  <Step title="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
  </Step>

  <Step title="Submit">
    Click **Create Issue** to submit. The issue receives a unique number identifier.
  </Step>
</Steps>

### Issue Creation from Code

```go theme={null}
// 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:

<Tabs>
  <Tab title="Markdown Templates">
    Create issue templates in `.gitea/ISSUE_TEMPLATE/` or `.github/ISSUE_TEMPLATE/`:

    ```markdown theme={null}
    ---
    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]
    ```
  </Tab>

  <Tab title="YAML Templates">
    Create structured forms with YAML:

    ```yaml theme={null}
    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
    ```
  </Tab>
</Tabs>

## Labels

Categorize and filter issues with labels:

### Creating and Managing Labels

<CardGroup cols={2}>
  <Card title="Label Properties" icon="tag">
    * **Name**: Label identifier
    * **Description**: Purpose of the label
    * **Color**: Visual identification (hex color)
    * **Exclusive**: Only one label from group
  </Card>

  <Card title="Default Labels" icon="tags">
    * `bug`: Something isn't working
    * `enhancement`: New feature or request
    * `documentation`: Documentation improvements
    * `duplicate`: Duplicate issue
    * `wontfix`: Will not be worked on
  </Card>
</CardGroup>

```go theme={null}
// 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`:

<Accordion title="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`
</Accordion>

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

## Milestones

Organize issues into release cycles or project phases:

### Creating Milestones

<Steps>
  <Step title="Navigate to Milestones">
    Go to **Issues** → **Milestones** in the repository
  </Step>

  <Step title="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)
  </Step>

  <Step title="Track Progress">
    * View open/closed issue counts
    * Monitor completion percentage
    * Filter issues by milestone
    * Close milestone when complete
  </Step>
</Steps>

### Milestone Management

```go theme={null}
// 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
}
```

<Note>
  Milestone completion percentage is automatically calculated based on open vs. closed issues.
</Note>

## Assignments

Assign issues to team members for accountability:

### Assigning Issues

<Tabs>
  <Tab title="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)
  </Tab>

  <Tab title="Via Comments">
    Use slash commands in issue comments:

    ```markdown theme={null}
    /assign @username
    /unassign @username
    /assign me
    ```
  </Tab>
</Tabs>

## Issue Comments

Collaborate through threaded discussions:

### Comment Features

<CardGroup cols={2}>
  <Card title="Rich Content" icon="markdown">
    * Full markdown support
    * Code blocks with syntax highlighting
    * Image and file attachments
    * Emoji reactions
    * @mentions for notifications
  </Card>

  <Card title="Actions" icon="bolt">
    * Edit comment history
    * Delete comments
    * Quote reply
    * React with emoji
    * Mark as resolved
  </Card>
</CardGroup>

### Slash Commands

Perform actions directly from comments:

```markdown theme={null}
/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

<Tabs>
  <Tab title="Same Repository">
    ```markdown theme={null}
    #123 - Reference issue/PR #123
    Fixes #123 - Auto-close when merged
    Closes #123 - Auto-close when merged
    Resolves #123 - Auto-close when merged
    ```
  </Tab>

  <Tab title="Cross-Repository">
    ```markdown theme={null}
    user/repo#123 - Reference issue in another repo
    Fixes user/repo#123 - Auto-close external issue
    ```
  </Tab>

  <Tab title="Commit References">
    ```markdown theme={null}
    abc123def - Reference commit SHA
    user/repo@abc123def - Reference commit in another repo
    ```
  </Tab>
</Tabs>

## Dependencies

Track issue dependencies to manage blockers:

<Steps>
  <Step title="Add Dependency">
    In the issue sidebar, use **Dependencies** section to add blocking or blocked-by issues
  </Step>

  <Step title="View Dependency Graph">
    See visual representation of issue dependencies in the issue view
  </Step>

  <Step title="Resolve Dependencies">
    Dependencies are automatically updated when blocking issues are closed
  </Step>
</Steps>

## Time Tracking

Track time spent on issues:

<CardGroup cols={2}>
  <Card title="Estimate Time" icon="clock">
    Set time estimates for planning:

    * Add estimated time in issue
    * Use format: `2h`, `30m`, `1d 4h`
    * Update estimates as needed
  </Card>

  <Card title="Track Time" icon="stopwatch">
    Record actual time spent:

    * Start/stop timer in issue
    * Manually add time entries
    * View total time spent
    * Compare estimate vs. actual
  </Card>
</CardGroup>

## Issue Filtering and Search

### Filter Options

<Accordion title="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
</Accordion>

### Search Syntax

```bash theme={null}
# 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

<CardGroup cols={2}>
  <Card title="Automatic Notifications" icon="bell">
    * Issue creation
    * Assignment changes
    * Mentions (@username)
    * Comment replies
    * Status changes
  </Card>

  <Card title="Subscription Management" icon="envelope">
    * Watch repository (all issues)
    * Subscribe to specific issues
    * Unsubscribe from issues
    * Configure notification preferences
  </Card>
</CardGroup>

## Issue Locking

Lock conversations to prevent further comments:

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

## 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:

```markdown theme={null}
Fixes #123
Closes #456
Resolves #789
```

## Best Practices

<Accordion title="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
</Accordion>

## See Also

* [Pull Requests](/features/pull-requests) - Code review workflow
* [Projects](/features/projects) - Kanban boards for issue tracking
* [Repositories](/features/repositories) - Repository management