# Org-Level Labels

Labels scoped to an organization. Org-level labels are **inherited by ALL repositories** within that organization. They appear alongside repo-level labels when viewing issues, but they are managed separately and have their own ID space.

## Key Differences from Repo Labels

- Org labels are visible in every repo under the org without explicitly creating them per-repo.
- An org label with `id: 5` is a **different label** than a repo label with `id: 5` — even in the same repo.
- Org labels can only be created/edited/deleted through the org endpoints, not through repo endpoints.
- When listing labels on an issue, both repo labels and org labels appear in the same `labels` array.

## Endpoints

### List org labels

```
GET /orgs/{org}/labels
```

**Query parameters:**
| Param | Type | Description |
|-------|------|-------------|
| `page` | integer | Page number (1-based) |
| `limit` | integer | Items per page |

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/labels?page=1&limit=50"
```

### Create an org label

```
POST /orgs/{org}/labels
```

**Body: CreateLabelOption** (same schema as repo labels)

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `name` | string | **yes** | Label name |
| `color` | string | **yes** | 6-char hex color, no `#` prefix |
| `description` | string | no | Label description |
| `exclusive` | boolean | no | Whether this label is exclusive |
| `is_archived` | boolean | no | Whether this label is archived |

```bash
# Create an org-wide "team" label
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Team/Backend",
    "color": "{color}",
    "description": "{label_description}",
    "exclusive": true
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/labels"

# Create a non-exclusive org label
curl -s -X POST \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "needs-triage",
    "color": "{color}",
    "description": "{label_description}"
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/labels"
```

### Get an org label

```
GET /orgs/{org}/labels/{id}
```

```bash
curl -s \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/labels/{label_id}"
```

### Edit an org label

```
PATCH /orgs/{org}/labels/{id}
```

**Body: EditLabelOption** — All fields are optional.

| Field | Type | Description |
|-------|------|-------------|
| `name` | string | New name |
| `color` | string | New hex color (no `#`) |
| `description` | string | New description |
| `exclusive` | boolean | New exclusive status |
| `is_archived` | boolean | New archived status |

```bash
curl -s -X PATCH \
  -H "Authorization: token ${FORGEJO_PAT}" \
  -H "Content-Type: application/json" \
  -d '{
    "description": "{label_description}",
    "color": "{color}"
  }' \
  "${FORGEJO_URL}/api/v1/orgs/{org}/labels/{label_id}"
```

### Delete an org label

```
DELETE /orgs/{org}/labels/{id}
```

This removes the org label definition and removes it from all issues across all repos in the org.

```bash
curl -s -X DELETE \
  -H "Authorization: token ${FORGEJO_PAT}" \
  "${FORGEJO_URL}/api/v1/orgs/{org}/labels/{label_id}"
```

## Typical Use Cases for Org Labels

1. **Cross-repo categorization** — Labels like `needs-triage`, `security`, `documentation` that should be consistent across all repos.
2. **Team ownership** — Exclusive labels like `Team/Backend`, `Team/Frontend`, `Team/Infra` to assign issue ownership.
3. **Org-wide priority** — `Priority/Critical`, `Priority/High`, etc. that follow the same scheme everywhere.
4. **Workflow states** — `Status/Backlog`, `Status/In Progress`, `Status/Review` for org-wide process tracking.

## Example: Bootstrap Org Labels

```bash
ORG="{org}"

# Workflow status labels (exclusive)
for entry in "Status/Backlog:{color}" "Status/In Progress:{color}" "Status/Review:{color}" "Status/Done:{color}"; do
  name="${entry%%:*}"
  color="${entry##*:}"
  curl -s -X POST \
    -H "Authorization: token ${FORGEJO_PAT}" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"${name}\", \"color\": \"${color}\", \"exclusive\": true}" \
    "${FORGEJO_URL}/api/v1/orgs/${ORG}/labels"
done

# General labels (non-exclusive)
for entry in "security:{color}" "documentation:{color}" "needs-triage:{color}"; do
  name="${entry%%:*}"
  color="${entry##*:}"
  curl -s -X POST \
    -H "Authorization: token ${FORGEJO_PAT}" \
    -H "Content-Type: application/json" \
    -d "{\"name\": \"${name}\", \"color\": \"${color}\", \"exclusive\": false}" \
    "${FORGEJO_URL}/api/v1/orgs/${ORG}/labels"
done
```
