3DCityDB Labels

GitHub label management system for the 3DCityDB project ecosystem. Maintains consistent issue labels across multiple repositories with automated synchronization and markdown documentation generation.

Managed repositories:

• 3dcitydb/3dcitydb
• 3dcitydb/citydb-tool
• 3dcitydb/3dcitydb-mkdocs

Current labels: See LABELS.md for the full label reference with badge previews, grouped by category.

Prerequisites

• Python 3
• pip

Installation

git clone https://github.com/3dcitydb/3dcitydb-labels.git
cd 3dcitydb-labels
pip install -r requirements.txt

Usage

Generate label documentation

Produces a markdown file with shields.io badge previews for all labels, grouped by category.

# Print to stdout
python generate_label_docs.py

# Write to file
python generate_label_docs.py --output LABELS.md

# Use a custom labels file
python generate_label_docs.py --file my-labels.json

Flag	Description
--file	Path to labels JSON file (default: labels.json)
--output, -o	Output file path (default: stdout)

Sync labels to GitHub

Applies labels from labels.json to the configured GitHub repositories via the REST API (v3). By default, only creates or updates labels. Use --remove-all to delete all existing labels before syncing for an exact match with the JSON file.

Token scopes: The access token needs the following permissions:

• Classic token: repo scope (or public_repo if all target repositories are public)
• Fine-grained token: read and write on at least one of Issues or Pull requests for each target repository

# Preview changes (no modifications)
python sync_labels.py --token $GITHUB_TOKEN --dry-run

# Sync labels to all repositories
python sync_labels.py --token $GITHUB_TOKEN

# Sync labels to a specific repository
python sync_labels.py --token $GITHUB_TOKEN --repos 3dcitydb/3dcitydb

# Remove all existing labels before syncing (exact match with JSON)
python sync_labels.py --token $GITHUB_TOKEN --remove-all

# Preview remove-all + sync (no modifications)
python sync_labels.py --token $GITHUB_TOKEN --remove-all --dry-run

# Remove all existing labels without syncing
python sync_labels.py --token $GITHUB_TOKEN --remove-only

# Preview remove-only (no modifications)
python sync_labels.py --token $GITHUB_TOKEN --remove-only --dry-run

# Sync to multiple specific repositories
python sync_labels.py --token $GITHUB_TOKEN --repos 3dcitydb/3dcitydb 3dcitydb/citydb-tool

# Use a custom labels file
python sync_labels.py --token $GITHUB_TOKEN --file my-labels.json

Flag	Description
--token	GitHub personal access token (or set GITHUB_TOKEN env var)
--file	Path to labels JSON file (default: labels.json)
--repos	One or more owner/repo to sync (default: all repos in JSON file)
--dry-run	Show what would change without applying
--remove-all	Remove all existing labels from target repos before syncing
--remove-only	Remove all existing labels from target repos without syncing

Label name matching is case-insensitive during sync.

Label schema (labels.json)

All label data is defined in a single file, labels.json, which serves as the single source of truth.

Key	Description
repositories	List of owner/repo strings to sync
groups	Label category definitions with name, base_color, and description. Used only for documentation generation — groups are not synced as GitHub labels.
shared_labels	Labels applied to all repositories. Each has name, color, description, and group.
repo_labels	Map of owner/repo to a list of repository-specific labels (domain tags).

Colors are stored as hex values without the # prefix (e.g., "D62728"). Label names use a hierarchical colon format (e.g., type: bug, domain: schema). Label descriptions must not exceed 100 characters (GitHub API limit).

Label groups

Group	Base Color	Description
Type	#1F77B4	Identifies what kind of work the issue represents
Status	#9467BD	Shows the issue's current progress state
Priority	#D62728	Reflects importance and urgency
Contribution	#FF7F0E	Related to community participation
Release	#17BECF	Versioning, regressions, backports
Infrastructure and others	#7F7F7F	CI/CD and repository maintenance, data, and others
Domain	#2CA02C	Indicates which subsystem or concept is affected. These tags are different for each repo.

Workflow

1. Edit labels.json (add/modify labels)
2. Run python generate_label_docs.py --output LABELS.md to regenerate docs
3. Run python sync_labels.py --dry-run --token $GITHUB_TOKEN to preview changes
4. Run python sync_labels.py --token $GITHUB_TOKEN to apply to GitHub

File overview

File	Description
labels.json	Single source of truth for all label definitions
generate_label_docs.py	Generates LABELS.md with shields.io badge previews from labels.json
sync_labels.py	Syncs labels to GitHub repositories via the REST API
LABELS.md	Generated label documentation (do not edit manually)
requirements.txt	Python dependencies (requests)