Badge Documentation

Complete guide to all badge types supported by Badgetizr.

Overview
Configuration File
Available Badge Types
Badge Styling
Troubleshooting

Overview

Badgetizr supports multiple badge types that can be enabled and customized individually. All badges support custom icons from Simple Icons - use the icon slug from the website in your configuration.

Configuration File

Default location: .badgetizr.yml in your project root
Custom location: Use -c path/to/config.yml
Example file: See .badgetizr.yml.example in the repository

# Use default configuration
badgetizr --pr-id=123

# Use custom configuration
badgetizr -c my-config.yml --pr-id=123

Available Badge Types

🎫 Ticket Badge

Extracts ticket IDs from PR titles and creates clickable badges linking to your ticket system.

Status: Disabled by default Example: feat(ABC-123): Add new feature →

Configuration

badge_ticket:
  enabled: "true"
  settings:
    color: "blue"
    label: "JIRA"
    logo: "jirasoftware"
    sed_pattern: '.*\(([^)]+)\).*'
    url: "https://yourproject.atlassian.net/browse/%s"

Settings

Setting	Description	Default	Required
`color`	Badge color	`blue`	No
`label`	Badge label text	`JIRA`	No
`logo`	Simple Icons slug	`jirasoftware`	No
`sed_pattern`	Regex to extract ticket ID (requires capture group)	`.\(([^)]+)\).`	No
`url`	URL template (`%s` replaced with ticket ID)	Atlassian URL	Yes

Common Regex Patterns

To match [GH-123] format:

sed_pattern: '.*\[GH-([0-9]+)\].*'

To match feat(GH-123): format (conventional commits):

sed_pattern: '.*\(GH-([0-9]+)\):.*'

⚠️ Work In Progress (WIP) Badge

Automatically detects "WIP" in PR titles (case-insensitive) and displays a warning badge.

Status: Enabled by default Example: WIP: Fix bug →

Configuration

badge_wip:
  enabled: "true"
  settings:
    color: "yellow"
    label: "WIP"
    logo: "vlcmediaplayer"
    labelized: "work in progress"  # Optional: auto-manage GitHub/GitLab labels

Settings

Setting	Description	Default	Required
`color`	Badge color	`yellow`	No
`label`	Badge text	`WIP`	No
`logo`	Simple Icons slug	`vlcmediaplayer`	No
`labelized`	Auto-manage platform labels	-	No

Label Management

When labelized is configured, automatically adds/removes the specified label on the PR:

WIP detected: Badge shown + Label added
No WIP: Badge hidden + Label removed
Missing labels: Auto-created with appropriate colors

🚨 Hotfix Badge

Automatically detects hotfix PRs based on target branch and title, displaying a warning badge for urgent production fixes.

Status: Disabled by default Example: [HOTFIX] Fix bug → master →

Configuration

badge_hotfix:
  enabled: "true"
  settings:
    color: "red"
    text_color: "white"
    label: "HOTFIX"
    production_branch: "master"  # Your production branch (main/master/trunk)
    labelized: "Hotfix"  # Optional: auto-manage GitHub/GitLab labels

Settings

Setting	Description	Default	Required
`color`	Badge background color	`red`	No
`text_color`	Badge text color	`white`	No
`label`	Badge text	`HOTFIX`	No
`production_branch`	Production branch name	`master`	No
`labelized`	Auto-manage platform labels	-	No

Detection Logic

Simple and predictable: Badge appears when both conditions are met:

✅ MR/PR targets production branch (main/master or configured production_branch)
✅ Title contains "hotfix" (case insensitive)

Works on all CI platforms without additional configuration. No git history required.

Example scenarios:

[HOTFIX] Fix critical bug → master → ✅ Hotfix badge shown
Hotfix: urgent fix → main → ✅ Hotfix badge shown
[GL-123] Test - hotfix → master → ✅ Hotfix badge shown (hotfix anywhere in title)
Add new feature → master → ❌ Not a hotfix (no keyword)
Hotfix: bug fix → develop → ❌ Not a hotfix (not targeting production)

Label Management

When labelized is configured, automatically adds/removes the specified label:

Hotfix detected: Badge shown + Red label added
Not a hotfix: Badge hidden + Label removed
Label color: Always red (non-customizable for consistency)

📊 Dynamic Badges

Creates badges based on patterns found in PR descriptions, perfect for tracking task completion.

Status: Disabled by default Example: - [x] Tests added →

Configuration

badge_dynamic:
  enabled: "true"
  settings:
    patterns:
      - sed_pattern: "(- \\[x\\] Tests added)"
        label: "Tests"
        value: "Done"
        color: "green"
      - sed_pattern: "(- \\[ \\] Tests added)"
        label: "Tests"
        value: "Pending"
        color: "orange"

Pattern Settings

Each pattern in the patterns array supports:

Setting	Description	Default	Required
`sed_pattern`	Regex pattern (requires capture group)	-	Yes
`label`	Badge label	-	Yes
`value`	Badge value/status	-	Yes
`color`	Badge color	`grey`	No

Common Use Cases

Task Checklists:

patterns:
  - sed_pattern: "(- \\[x\\] Documentation updated)"
    label: "Docs"
    value: "Updated"
    color: "green"

Review Status:

patterns:
  - sed_pattern: "(Reviewed by: @\\w+)"
    label: "Review"
    value: "Complete"
    color: "blue"

🌿 Branch Badge

Highlights when a PR targets a branch other than the configured default.

Status: Disabled by default Example: PR to main →

Configuration

badge_base_branch:
  enabled: "true"
  settings:
    base_branch: "develop"
    color: "orange"
    label: "Target"

Settings

Setting	Description	Default	Required
`base_branch`	Expected default branch	`develop`	No
`color`	Badge color	`orange`	No
`label`	Badge label	`Target`	No

Requirements

CLI Parameter: --pr-destination-branch (required when enabled)
Behavior: Only shows badge when target branch differs from base_branch

🚀 CI Badge

Displays CI status and build information with direct links to CI pipeline runs. Supports both static builds and dynamic status updates during pipeline execution.

Status: Disabled by default Example:

Configuration

badge_ci:
  enabled: "true"
  settings:
    label_color: "black"
    label: "Build"
    logo: "github"
    color: "darkgreen"  # Used for static builds when no status provided

Settings

Setting	Description	Default	Required
`color`	Badge color for static builds	`purple`	No
`label_color`	Label background color	`black`	No
`label`	Badge label text	`CI`	No
`logo`	Simple Icons slug	`github`	No

CLI Parameters

Parameter	Description	Required
`--pr-build-url`	Build URL (badge is always clickable)	Yes
`--pr-build-number`	Build number (for static or passed/failed)	No
`--ci-status`	Status: `started`, `passed`, `warning`, `failed`	No
`--ci-text`	Custom text for badge	No

Usage Examples

Command Line Usage

# Static build badge (shows build number)
badgetizr --pr-id=123 \
  --pr-build-number=456 \
  --pr-build-url="https://ci.example.com/builds/456"

# CI status with custom text (intermediate steps)
badgetizr --pr-id=123 \
  --ci-status=started \
  --ci-text="Installing Dependencies" \
  --pr-build-url="https://ci.example.com/builds/456"

# CI final status with build number
badgetizr --pr-id=123 \
  --ci-status=passed \
  --pr-build-number=456 \
  --pr-build-url="https://ci.example.com/builds/456"

# CI final status with custom text (no build number)
badgetizr --pr-id=123 \
  --ci-status=failed \
  --ci-text="Tests Failed" \
  --pr-build-url="https://ci.example.com/builds/456"

GitHub Actions Workflow

name: CI Pipeline with Status Updates

on: [pull_request]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # CI Started
      - name: Update CI Status - Started
        uses: aiKrice/homebrew-badgetizr@latest
        with:
          pr_id: ${{ github.event.pull_request.number }}
          pr_build_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          ci_status: "started"
          ci_text: "Installing Dependencies"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      # Build steps
      - name: Install Dependencies
        run: npm install

      # Update status during tests
      - name: Update CI Status - Testing
        uses: aiKrice/homebrew-badgetizr@latest
        with:
          pr_id: ${{ github.event.pull_request.number }}
          pr_build_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          ci_status: "started"
          ci_text: "Running Tests"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: Run Tests
        run: npm test

      # Final status with build number
      - name: CI Success
        if: success()
        uses: aiKrice/homebrew-badgetizr@latest
        with:
          pr_id: ${{ github.event.pull_request.number }}
          pr_build_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          pr_build_number: ${{ github.run_id }}
          ci_status: "passed"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

      - name: CI Failed
        if: failure()
        uses: aiKrice/homebrew-badgetizr@latest
        with:
          pr_id: ${{ github.event.pull_request.number }}
          pr_build_url: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"
          pr_build_number: ${{ github.run_id }}
          ci_status: "failed"
        env:
          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Status Colors

started →
passed →
warning →
failed →

Badge Behavior

Text Display Logic:

started/warning: Uses --ci-text if provided, otherwise status name
passed/failed: Uses --pr-build-number if provided, otherwise --ci-text, otherwise status name
Static mode: Uses --pr-build-number (required) with configured color

Badge is always clickable and links to --pr-build-url

✅ Ready for Approval Badge

Automatically tracks checkbox completion status in PR descriptions and displays a badge when all checkboxes are completed. Also manages labels accordingly.

Status: Disabled by default Example: When all checkboxes are checked → + Label "Ready for Approval" is added

Configuration

badge_ready_for_approval:
  enabled: "true"
  settings:
    color: "green"
    label: "Ready"
    logo: "checkmark"
    labelized: "Ready for Approval"  # Optional: auto-manage GitHub/GitLab labels

Settings

Setting	Description	Default	Required
`color`	Badge color	`green`	No
`label`	Badge text	`Ready`	No
`logo`	Simple Icons slug	`checkmark`	No
`labelized`	Auto-manage platform labels	-	No

Detection Logic

Scans PR body for checkbox patterns: - [ ] (unchecked) and - [x] (checked)
All checkboxes checked: Badge displayed + Label added (green color)
Unchecked checkboxes exist: Badge hidden + Label removed
No configuration needed: Checkbox detection is automatic

Label Management

When labelized is configured, automatically adds/removes the specified label:

All checkboxes completed: Label added with green color
Pending checkboxes: Label removed
Missing labels: Auto-created with green color and appropriate description

Use Cases

Task Completion Tracking:

## Checklist
- [x] Code reviewed
- [ ] Tests added
- [x] Documentation updated

Result: Label "Ready for Approval" removed (1 unchecked item)

Ready for Review:

## Checklist
- [x] Code reviewed
- [x] Tests added
- [x] Documentation updated

Result: Label "Ready for Approval" added (all items completed)

Uh oh!

FilesExpand file tree

BADGES.md

Latest commit

History

BADGES.md

File metadata and controls

Badge Documentation

Table of Contents

Overview

Configuration File

Available Badge Types

🎫 Ticket Badge

Configuration

Settings

Common Regex Patterns

⚠️ Work In Progress (WIP) Badge

Configuration

Settings

Label Management

🚨 Hotfix Badge

Configuration

Settings

Detection Logic

Label Management

📊 Dynamic Badges

Configuration

Pattern Settings

Common Use Cases

🌿 Branch Badge

Configuration

Settings

Requirements

🚀 CI Badge

Configuration

Settings

CLI Parameters

Usage Examples

Command Line Usage

GitHub Actions Workflow

Status Colors

Badge Behavior

✅ Ready for Approval Badge

Configuration

Settings

Detection Logic

Label Management

Use Cases