GitHub Label Manager

A lightweight GitHub Action that automatically creates, updates, and manages repository labels from a YAML configuration file.
Keeps labels consistent and synchronized across repositories.

---

Features

• Automated Label Management – Create, update, and delete labels automatically
• Color Normalization – Handles hex color codes with or without #
• Detailed Outputs – Provides counts for created, updated, deleted, and ignored labels
• Enterprise Support – Works with GitHub Enterprise Server
• Ignore Flag – Skip specific labels during sync
• Multiple Sources – Load config from local files, URLs, or other repositories
• Optional Deletion – Control whether missing labels are removed
• YAML Configuration – Define labels in a simple, human-readable format

---

Usage

Basic Setup

name: Synchronize Labels
on:
  push:
    branches: [main]
    paths:
      - '.github/config/repository-labels.yml'

jobs:
  synchronize-labels:
    permissions:
      contents: read 
      issues: write
    runs-on: ubuntu-latest
    steps:
      - name: Synchronize repository labels
        uses: lukas-kuntze/devx-action-label-manager@main
        with:
          config_file: .github/config/repository-labels.yml
          github_token: ${{ secrets.GITHUB_TOKEN }}

---

Configuration

Inputs

Input	Description	Required	Default
config_file	Path, URL, or GitHub repo path to YAML configuration file	❌ No	.github/config/repository-labels.yml
delete_missing	Delete labels not in config	❌ No	false
github_api_url	GitHub API base URL (Enterprise)	❌ No	https://api.github.com
github_token	GitHub token for authentication	✅ Yes	${{ github.token }}

Outputs

Output	Description
labels_created	Number of labels created
labels_updated	Number of labels updated
labels_deleted	Number of labels deleted
labels_ignored	Number of labels ignored

---

Example Configuration

Create .github/config/repository-labels.yml:

labels:
  - name: docs
    description: This label marks tasks to update, improve, or extend project documentation.
    color: E4DA8A

  - name: feature
    description: This label marks tasks for developing or adding new functionality to the project.
    color: 154C79

  - name: fix
    description: This label marks tasks that fix issues or bugs in the code.
    color: BC0003

Field Descriptions:

• name – Label name (required)
• color – Hex color code with or without # (required)
• description – Short description (optional, ≤100 chars)
• ignore – Skip this label if true (optional)

---

Examples

Custom Configuration Sources

Local File

with:
  config_file: .github/config/repository-labels.yml

Remote URL

with:
  config_file: https://raw.githubusercontent.com/org/repo/main/repository-labels.yml

Shared GitHub Repository

with:
  config_file: organization/shared-configs/repository-labels.yml

---

Example: Conventional Commit Labels

labels:
  - name: chore
    description: This label marks routine tasks, maintenance, or non-functional changes.
    color: 83D09B

  - name: docs
    description: This label marks tasks to update, improve, or extend project documentation.
    color: E4DA8A

  - name: feat
    description: This label marks tasks for developing or adding new functionality to the project.
    color: 154C79

  - name: fix
    description: This label marks tasks that fix issues or bugs in the code.
    color: BC0003

Example: PR Size Labels

labels:
  - name: large
    description: Marks large pull requests (≤ 2000 lines changed).
    color: F66A0A

  - name: medium
    description: Marks medium-sized pull requests (≤ 500 lines changed).
    color: F5C518

  - name: oh lawd he comin
    description: Marks oversized pull requests (> 2000 lines changed). Such PRs should be split if possible.
    color: D73A4A

  - name: small
    description: Marks small pull requests (≤ 100 lines changed).
    color: 36B37E

  - name: teeny
    description: Marks very small pull requests (≤ 10 lines changed).
    color: B7EB8F

Example: Ignored Labels

labels:
  - name: blocked
    description: This label marks tasks that are blocked by dependencies, missing resources, or issues.
    color: FF0004
    ignore: true

  - name: needs clarification
    description: This label marks tasks that need more information or further discussion.
    color: 1F6DAD

---

GitHub Enterprise Support

- name: Synchronize Labels
  uses: lukas-kuntze/devx-action-label-manager@main
  with:
    config_file: .github/config/repository-labels.yml
    github_api_url: 'https://github.company.com/api/v3'
    github_token: ${{ secrets.GITHUB_TOKEN }}

---

How It Works

1. Load Configuration – Loads the YAML file via GitHub API, URL, or from another repository
2. Validate – Ensures valid names, colors, and uniqueness
3. Fetch Existing Labels – Retrieves all current repository labels
4. Sync Labels – Creates, updates, deletes, or skips based on settings
5. Report Results – Outputs statistics for created, updated, deleted, and ignored labels

---

Requirements

• contents: read permission for the workflow (to read configuration files)
• issues: write permission for the workflow (to manage labels)
• No checkout required – configuration is loaded via GitHub API

---

Author

Created and maintained by Lukas Kuntze
Software Developer · Software Development & IT Services Kuntze
GitHub: lukas-kuntze

---

Designed for internal automation and engineering workflows.
Public use is possible but not officially supported.