# Custom Issue Statuses

Custom issue statuses extend Gitea's binary Open/Closed model with org-defined workflow states. Each status has a name, color, and an optional "closes issue" flag that triggers automatic close/reopen when selected.

## Overview

Statuses are defined at the **organization level** and appear in the issue sidebar for all repositories under that organization. This is the same pattern as org-level labels and custom fields.

### Key Concepts

- **Status definitions** are managed in Org Settings > Issue Statuses
- **Status selection** appears as a dropdown in the issue sidebar
- **Auto close/reopen** — selecting a status with `closes_issue = true` automatically closes the issue; switching to a non-closing status reopens it
- **Status is supplemental** — the existing Open/Closed binary state is preserved; statuses add granularity on top

## Org Settings

Navigate to **Organization Settings > Issue Statuses** to manage status definitions.

Each status has:

| Field | Description |
|-------|-------------|
| Name | Display name (e.g., "In Progress", "Won't Fix", "Blocked") |
| Color | Hex color for visual distinction (e.g., `#2563eb`) |
| Description | Help text shown to users |
| Closes Issue | When checked, selecting this status automatically closes the issue |
| Sort Order | Controls display order in dropdowns (ascending) |
| Is Active | Inactive statuses are hidden from dropdowns but preserved on existing issues |

### Default Statuses (auto-seeded)

| Status | Color | Closes Issue | Use Case |
|--------|-------|:------------:|----------|
| In Progress | Blue | No | Work is actively being done |
| Needs Info | Yellow | No | Waiting for more information |
| Blocked | Red | No | Cannot proceed due to dependency |
| Resolved | Green | Yes | Fix implemented and verified |
| Won't Fix | Gray | Yes | Decided not to address |
| Duplicate | Purple | Yes | Already tracked elsewhere |
| Pending: Design | Lavender | No | Waiting on design work |
| Pending: Testing | Yellow | No | Waiting for testing |
| Pending: Review | Green | No | Waiting for code review |
| Pending: Feedback | Pink | No | Waiting for feedback |
| Pending: Documentation | Purple | No | Waiting for docs |
| Pending: Deployment | Blue | No | Ready to deploy |
| Pending: Dependency | Light Blue | No | Blocked by external dependency |

Statuses are auto-seeded when an org first accesses them. Admins can add, edit, reorder, or deactivate statuses.

## Comment Form Integration

The status dropdown **replaces the close/reopen button** in the comment form footer for issues with org statuses:
- Open issues show all statuses plus a "Close" option
- Selecting a status with `closes_issue = true` auto-closes the issue
- Closed issues show only "Reopen" for non-admin users
- Admins see the full dropdown on closed issues including "Reopen"
- PRs still use the standard close/reopen button

## Issue List Badges

Status shows as a colored badge on each issue in the issue list view, alongside Type and Priority badges.

## Issue Sidebar

Status also appears as a read-only display in the sidebar (the editable control is in the comment form). The dropdown:
- Displays a colored left border on each option
- Shows a power symbol on statuses that close the issue
- Selecting "—" (empty) clears the status

### Auto Close/Reopen Behavior

| Current State | Selected Status | Result |
|:---:|---|---|
| Open | Status with `closes_issue = true` | Issue is closed automatically |
| Closed | Status with `closes_issue = false` | Issue is reopened automatically |
| Open | Status with `closes_issue = false` | Status set, issue stays open |
| Closed | Status with `closes_issue = true` | Status set, issue stays closed |

All close/reopen actions go through the standard Gitea service layer, so webhooks, notifications, and timeline events fire normally.

## Database

### Tables

**`issue_status_def`** (migration v346) — org-level status definitions

| Column | Type | Description |
|--------|------|-------------|
| id | bigint | Primary key |
| org_id | bigint | Organization ID |
| name | varchar | Status name |
| color | varchar(7) | Hex color |
| description | text | Help text |
| closes_issue | bool | Auto-close flag |
| sort_order | int | Display order |
| is_active | bool | Visibility flag |

**`issue`** table — added `status_id` column (bigint, default 0)

### Cascade on Delete

When a status definition is deleted, all issues referencing it have their `status_id` set to 0 (cleared). Issues are not closed or reopened during deletion.

## Routes

### Web Routes (Org Settings)

| Method | Path | Handler |
|--------|------|---------|
| GET | `/org/{org}/settings/issue-statuses` | `SettingsIssueStatuses` |
| POST | `/org/{org}/settings/issue-statuses` | `SettingsIssueStatusesCreatePost` |
| POST | `/org/{org}/settings/issue-statuses/{id}/edit` | `SettingsIssueStatusesEditPost` |
| POST | `/org/{org}/settings/issue-statuses/{id}/delete` | `SettingsIssueStatusesDeletePost` |

### Web Routes (Issue Sidebar)

| Method | Path | Handler |
|--------|------|---------|
| POST | `/{owner}/{repo}/issues/{id}/custom-status` | `UpdateIssueCustomStatus` |

---

| Revision | Date | Author | Description |
|---|---|---|---|
| 1.0 | 2026-06-06 | Jonathan Miller (@jmiller) | Initial version |