# Issue labels

Labels let you categorize issues and pull requests by type, priority, status, or anything else your team needs. Apply them from the sidebar of any issue or pull request, then filter lists by label to focus on what matters.

Labels are stock Forgejo. This page covers how they work on Codebahn and how to manage them with the CLI and MCP server. For the full UI reference, see the [upstream labels documentation](https://forgejo.org/docs/v15.0/user/labels/).

## Repository and organization labels

Labels exist at two levels:

- **Repository labels** belong to a single repository. Create and manage them from the repository's **Issues > Labels** page.
- **Organization labels** belong to an organization and are available to every repository in it automatically. Create and manage them from the organization's **Settings > Labels** page.

Both types appear in the label picker on any issue or pull request. Repository labels show first, followed by organization labels after a divider. Organization labels are read-only in the repository view; edit or delete them from the organization settings.

A repository owned by a personal account (not an organization) has only repository labels.

### Which level to use

Use **organization labels** for categories that apply across repositories, like `type/bug`, `type/feature`, or `priority/high`. Use **repository labels** for things specific to one repository.

If you started with repository-level defaults and later set up organization labels for the same purpose, delete the old repository labels to avoid duplicates. Go to the repository's **Issues > Labels** and delete the ones you no longer need. Deleting a label removes it from every issue in that repository and removes the related timeline entries ("added label", "removed label").

### Label presets

When you create a repository or initialize organization labels, Codebahn offers two presets:

- **Default**: seven basic labels (bug, duplicate, enhancement, help wanted, invalid, question, wontfix).
- **Advanced**: eighteen labels organized by kind, compatibility, review status, issue status, and priority. Eleven of them use [exclusive scopes](https://forgejo.org/docs/v15.0/user/labels/#scoped-labels).

The preset picker appears only when the scope has no labels yet. Applying a preset to a scope that already has labels creates duplicates.

## Manage labels with the CLI

The [Codebahn CLI](/docs/cli/) supports label management through the `issue` command group:

| Command | What it does |
|---|---|
| `issue labels` | List labels for a repository |
| `issue create-label` | Create a label |
| `issue edit-label` | Edit a label's name, color, or description |
| `issue delete-label` | Delete a label |
| `issue add-labels` | Add labels to an issue |
| `issue remove-labels` | Remove labels from an issue |

## Manage labels with the MCP server

The [MCP server](/docs/mcp/) exposes a `labels` tool with actions for listing, creating, editing, deleting, and adding or removing labels from issues. See the [labels tool reference](/docs/mcp/tools/#labels) for the full parameter list.

A few details worth knowing:

- **Listing** merges repository and organization labels and tags each with its scope (`repo` or `org`). Pass `include_org_labels: false` to list only repository labels.
- **Organization scope**: omit the `repo` parameter to work with organization-level labels.
- **Adding labels** to an issue uses label **names**. **Removing labels** uses label **IDs**. The list response includes both.

## Labels and migration

When you [import a repository](/docs/migrate-from-github/) from GitHub, GitLab, or another Forgejo instance, labels are carried over as repository labels.

[Mirrors](/docs/mirror-github-repos/) sync only Git data (commits, branches, tags). Labels are not mirrored.

When you [export your data](/docs/export/), repository labels are included in the per-repository archive.
