Labels categorize issues. Milestones group issues into releases or sprints. Together they provide powerful filtering and progress tracking.

Labels

Creating Labels

Via Web UI

1. Go to Issues → Labels → New Label
2. Configure:
   • Name: Short identifier (e.g., bug, feature)
   • Description: What it means
   • Color: Hex color code
3. Click Create

Via API

curl -X POST /api/v1/repos/org/repo/labels \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "name": "security",
    "description": "Security-related issues",
    "color": "d73a4a"
  }'

Default Labels

Kizuna creates common labels automatically:

Label	Color	Use
bug	#d73a4a	Something is broken
feature	#a2eeef	New functionality
documentation	#0075ca	Docs improvement
good first issue	#7057ff	For newcomers
help wanted	#008672	Community contribution
duplicate	#cfd3d7	Already reported
invalid	#e4e669	Not an issue

Label Categories

Use prefixes for organization:

priority-critical
priority-high
priority-medium
priority-low

type-bug
type-feature
type-task
type-docs

area-auth
area-api
area-ui
area-db

Applying Labels

# Add labels
curl -X POST /api/v1/repos/org/repo/issues/42/labels \
  -d '{"labels": ["bug", "priority-high"]}'

# Remove label
curl -X DELETE /api/v1/repos/org/repo/issues/42/labels/bug

# Set labels (replaces all)
curl -X PUT /api/v1/repos/org/repo/issues/42/labels \
  -d '{"labels": ["feature"]}'

Milestones

Creating Milestones

Via Web UI

1. Go to Issues → Milestones → New Milestone
2. Configure:
   • Title: Sprint or release name
   • Description: Goals, scope
   • Due Date: When it should complete
3. Click Create

Via API

curl -X POST /api/v1/repos/org/repo/milestones \
  -H "Authorization: Bearer $TOKEN" \
  -d '{
    "title": "v1.0.0 Release",
    "description": "First stable release",
    "due_on": "2026-04-01T00:00:00Z"
  }'

Milestone Progress

View progress in milestone page:

v1.0.0 Release — Due April 1, 2026
━━━━━━━━━░ 85% complete

Open: 3 | Closed: 17 | Total: 20

Assigning Issues to Milestones

curl -X PATCH /api/v1/repos/org/repo/issues/42 \
  -d '{"milestone": 1}'

Or via web UI:

1. Open issue
2. Select milestone in sidebar

Filtering

By Label

# Issues with bug label
curl /api/v1/repos/org/repo/issues?labels=bug

# Issues with ANY of these labels
curl /api/v1/repos/org/repo/issues?labels=bug,security

# Issues with ALL labels (when supported)
curl /api/v1/repos/org/repo/issues?labels=bug&labels=priority-high

By Milestone

# Issues in milestone
curl /api/v1/repos/org/repo/issues?milestone=v1.0.0

# Issues without milestone
curl /api/v1/repos/org/repo/issues?milestone=none

Combined

# Critical bugs in v1.0.0
curl /api/v1/repos/org/repo/issues?labels=bug,priority-critical&milestone=v1.0.0

Best Practices

Labels

1. Consistent naming — Use prefixes for categories
2. Clear descriptions — Help team understand meaning
3. Not too many — 10-15 labels max usually
4. Color coding — Visual distinction (red = urgent)
5. Regular cleanup — Remove unused labels

Milestones

1. Time-boxed — 1-4 weeks typical for sprints
2. Achievable scope — Don't overcommit
3. Clear goals — What defines success?
4. Regular review — Progress check-ins
5. Close when done — Archive completed milestones

Automation

Auto-Labeling

Configure rules in .kizuna/workflows/labeler.yml:

name: Labeler
on:
  issues:
    types: [opened]

jobs:
  label:
    runs-on: ubuntu-latest
    steps:
      - uses: kizuna/labeler-action@v1
        with:
          config: |
            bug:
              - '(?i)bug|error|broken|fail'
            feature:
              - '(?i)feature|enhancement|add'

Milestone Automation

Auto-assign based on issue content or templates.

Summary

Labels and milestones provide:

• Categorization — Organize by type, priority, area
• Progress tracking — See milestone completion
• Filtering — Find relevant issues quickly
• Reporting — Metrics by label/milestone

They're essential for managing issue volume at scale.