Topics

#ci #code-reviews #github-actions #productivity #pull-requests

Language breakdown

Shell 98.7%

Makefile 0.7%

Ruby 0.6%

▸ Files click to expand

README

Badgetizr

Add badges to your pull requests and increase your productivity 🚀.

What is Badgetizr?

Badgetizr automatically adds customizable badges to your GitHub and GitLab pull/merge requests to boost team productivity. With support for multiple badge types and full CI/CD integration, it helps teams:

🎯 Track ticket references automatically from PR titles
⚠️ Identify work-in-progress pull requests clearly
📊 Monitor CI/CD status without clicking through pipelines
✅ Visualize completion status of checklists and tasks
🎯 Highlight target branches for better merge awareness

Multi-Platform Support

✅ GitHub - Full support via GitHub CLI ✅ GitLab - Full support via GitLab CLI ✅ GitHub Actions - Native integration ✅ GitLab CI - Native integration ✅ Bitrise CI - Custom step for macOS and Linux

Installation

CI/CD Integration (Automated)

GitHub Actions

Add this to your workflow (.github/workflows/*.yml):

jobs:
  badgetizr:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout
        uses: actions/checkout@v5
- name: Run Badgetizr         uses: aiKrice/homebrew-badgetizr@3.0.3         with:           prid: ${{ github.event.pullrequest.number }}           configuration: .badgetizr.yml           prdestinationbranch: ${{ github.event.pull_request.base.ref }}           prbuildnumber: ${{ github.run_id }}           prbuildurl: "https://github.com/${{ github.repository }}/actions/runs/${{ github.run_id }}"         env:           GHTOKEN: ${{ secrets.GITHUBTOKEN }}

GitLab CI

Add this to your .gitlab-ci.yml:

Live example: badgetizr-integration GitLab project

Works for both GitLab.com and self-managed instances:

badgetizr:
  stage: build
  image: alpine:latest
  variables:
    BADGETIZR_VERSION: "3.0.3"
    GLAB_VERSION: "1.78.3"
    # Auto-detects: gitlab.com for SaaS, your instance for self-managed
    GITLABHOST: "${CISERVER_HOST}"
    BUILDURL: "https://${CISERVERHOST}/${CIPROJECTPATH}/-/pipelines/${CIPIPELINE_ID}"
    CONFIG_PATH: "../.badgetizr.yml"
    GITLABTOKEN: $GITLABACCESS_TOKEN
  before_script:
    - apk add --no-cache curl bash yq
    - curl -sSL "https://gitlab.com/gitlab-org/cli/-/releases/v${GLABVERSION}/downloads/glab${GLABVERSION}linux_amd64.tar.gz" | tar -xz -C /tmp
    - mv /tmp/bin/glab /usr/local/bin/glab && chmod +x /usr/local/bin/glab
    - curl -sSL https://github.com/aiKrice/homebrew-badgetizr/archive/refs/tags/${BADGETIZR_VERSION}.tar.gz | tar -xz
    - cd homebrew-badgetizr-*
    - export GITLABHOST="${CISERVER_HOST}"
  script:
    - |
      ./badgetizr -c ${CONFIG_PATH} \
      --pr-id=$CIMERGEREQUEST_IID \
      --pr-destination-branch=$CIMERGEREQUESTTARGETBRANCH_NAME \
      --pr-build-number=$CIPIPELINEID \
      --pr-build-url=${BUILD_URL} \
      --provider=gitlab
  rules:
    - if: $CIPIPELINESOURCE == "mergerequestevent"

Key features:

✅ Universal: Works for GitLab.com and self-managed instances automatically
✅ Centralized variables: Easy to update versions and paths
✅ Auto-detection: CISERVERHOST adapts to your environment
✅ Customizable: Modify variables at the top for your setup

For custom ports or URLs: Replace BUILDURL with your specific format (e.g., using $CISERVERPORT or $CISERVER_URL)

Bitrise CI

Add the Badgetizr step to your Bitrise workflow. Works on both macOS and Linux stacks.

📚 Complete Documentation: See BITRISE.md for detailed setup instructions, troubleshooting, and advanced configuration.

Quick Setup (Official StepLib - Recommended):

workflows:
  primary:
    steps:
      - git-clone: {}
      - badgetizr@3.0.3:
          title: Run Badgetizr
          inputs:
            - prid: $BITRISEPULL_REQUEST
            - prbuildurl: $BITRISEBUILDURL
            - githubtoken: $GITHUBTOKEN

Alternative (Custom Git Step):

workflows:
  primary:
    steps:
      - git-clone: {}
      - git::https://github.com/aiKrice/homebrew-badgetizr.git@3.0.3:
          title: Run Badgetizr
          inputs:
            - prid: $BITRISEPULL_REQUEST
            - prbuildurl: $BITRISEBUILDURL
            - githubtoken: $GITHUBTOKEN

Configure secrets in Bitrise:

Add GITHUBTOKEN (for GitHub PRs) or GITLABTOKEN (for GitLab MRs) to your Bitrise Secrets

Manual Installation

Homebrew (macOS/Linux)

# Add the tap and install
brew tap aiKrice/badgetizr
brew install aiKrice/badgetizr/badgetizr
Configure authentication
export GITHUBTOKEN="yourgithub_token"     # For GitHub
export GITLABTOKEN="yourgitlab_token"     # For GitLab
export GITLAB_HOST="gitlab.example.com"     # For self-managed GitLab (optional)

Direct Installation (macOS/Linux)

For systems without Homebrew or for development purposes:

# Download latest release
TAG=$(curl -s https://api.github.com/repos/aiKrice/homebrew-badgetizr/releases/latest | grep '"tag_name":' | sed -E 's/."([^"]+)"./\1/')
curl -L -o badgetizr-latest.tar.gz "https://github.com/aiKrice/homebrew-badgetizr/archive/refs/tags/$TAG.tar.gz"
tar -xz --strip-components=1 -f badgetizr-latest.tar.gz
Install runtime dependencies (gh/glab, yq)
./configure
For contributors: install development tools (shellcheck, shfmt, bats, kcov)
./configure --contributor
Configure authentication
export GITHUBTOKEN="yourgithub_token"     # For GitHub
export GITLABTOKEN="yourgitlab_token"     # For GitLab
export GITLAB_HOST="gitlab.example.com"     # For self-managed GitLab (optional)

Usage

Command Line Options

badgetizr [options]

Required Options

| Option | Description | |--------|-------------| | --pr-id <id> | Specify the pull/merge request ID |

Optional Options

| Option | Description | Default | |--------|-------------|---------| | -c <file>, --configuration <file> | Path to configuration file | .badgetizr.yml | | --pr-destination-branch <branch> | Target branch (required for branch badge) | - | | --pr-build-number <number> | Build number (for passed/failed statuses or static builds) | - | | --pr-build-url <url> | Build URL (required for CI badge) | - | | --ci-status <status> | CI status: started, passed, warning, failed | - | | --ci-text <text> | Custom text for CI badge | - | | --provider <provider> | Force provider (github or gitlab) | Auto-detected | | -v, --version | Display version | - | | -h, --help | Display help | - |

Basic Examples

# Minimal usage (auto-detects GitHub/GitLab)
badgetizr --pr-id=123
With custom configuration
badgetizr -c custom.yml --pr-id=123
Force specific provider
badgetizr --provider=gitlab --pr-id=123
Complete example with all options
badgetizr \
  --pr-id=123 \
  --pr-destination-branch=main \
  --pr-build-number=456 \
  --pr-build-url="https://github.com/owner/repo/actions/runs/456" \
  --provider=github

Provider Detection

Badgetizr automatically detects your platform:

GitHub: Uses gh CLI with GITHUBTOKEN or GHTOKEN
GitLab: Uses glab CLI with GITLAB_TOKEN

- For self-managed GitLab: Set GITLAB_HOST environment variable

Auto-detection: Based on git remote get-url origin
Manual override: Use --provider=github or --provider=gitlab

Configuration

Badgetizr uses a YAML configuration file to define which badges to display and their settings.

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

Badges

Badgetizr supports multiple badge types that can be customized to track different aspects of your pull requests.

📖 Complete Badge Documentation

Quick Overview

| Badge Type | Default Status | Purpose | Preview | Labelized | |-----------|----------------|---------|---------|-----------| | 🎫 Ticket | Disabled | Links to ticket systems (Jira, GitHub Issues, etc.) | | - | | ⚠️ WIP | Enabled | Identifies work-in-progress pull requests | | ✅ | | 🚨 Hotfix | Disabled | PR to production + "hotfix" in title | | ✅ | | 📊 Dynamic | Disabled | Tracks checklist completion and custom patterns | | - | | 🌿 Branch | Disabled | Highlights non-standard target branches | | - | | 🚀 CI | Disabled | Shows CI status and build info with clickable links | | - | | ✅ Ready for Approval | Disabled | Shows badge when all checkboxes are completed | | ✅ |

Configuration

Badgetizr uses a YAML configuration file to define badge settings:

Default location: .badgetizr.yml in your project root
Custom location: Use -c path/to/config.yml
Icons: All badges support icons from Simple Icons

Multiple Configurations

Badgetizr supports different configuration files for different contexts:

# Feature development
badgetizr -c .badgetizr-feature.yml --pr-id=123
Hotfix releases
badgetizr -c .badgetizr-hotfix.yml --pr-id=124
Release candidates
badgetizr -c .badgetizr-release.yml --pr-id=125

Example configurations:

.badgetizr-hotfix.yml - Minimal badges for urgent fixes:

badge_wip:   enabled: "true" badgebasebranch:   enabled: "true"  # Show target branch clearly   settings:     base_branch: "main"     color: "red"     label: "HOTFIX" Other badges disabled for speed

.badgetizr-release.yml - Full validation for releases:

badge_wip:   enabled: "true" badge_dynamic:   enabled: "true"   settings:     patterns:       - sed_pattern: "(- \\[x\\] Changelog updated)"         label: "Changelog"         value: "Updated"         color: "green"       - sed_pattern: "(- \\[x\\] Version bumped)"         label: "Version"         value: "Bumped"         color: "blue"       - sed_pattern: "(- \\[x\\] Tests passing)"         label: "Tests"         value: "Passing"         color: "green"

.badgetizr-feature.yml - Standard development workflow:

badge_wip:   enabled: "true" badge_ticket:   enabled: "true"   settings:     sed_pattern: '.\[FEAT-([0-9]+)\].'     label: "Feature"     url: "https://yourproject.atlassian.net/browse/FEAT-%s" badge_dynamic:   enabled: "true"   settings:     patterns:       - sed_pattern: "(- \\[x\\] Unit tests added)"         label: "Tests"         value: "Added"         color: "green"

Contributing

We welcome contributions to Badgetizr! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated.

🤝 Complete Contributing Guide

Quick Start

| Step | Action | Command | |------|--------|---------| | 1️⃣ Fork & Clone | Fork the repository and clone locally | git clone https://github.com/your-username/homebrew-badgetizr.git | | 2️⃣ Setup | Install dependencies and configure tokens | ./configure && export GITHUB_TOKEN="..." | | 3️⃣ Test | Test your changes with real PRs | ./badgetizr --pr-id=123 | | 4️⃣ PR Rule | Run Badgetizr on your own PR | ./badgetizr --pr-id=YOURPRNUMBER |

Contributing Areas

🐛 Bug Fixes: Authentication, badge rendering, configuration parsing
✨ New Features: Additional badge types, CI/CD platform support
📚 Documentation: README improvements, troubleshooting guides
🧪 Testing: Unit tests, integration tests, cross-platform compatibility

Running Tests

Badgetizr includes a comprehensive test suite using bats-core.

Install bats-core:

# Homebrew brew install bats-core
npm
npm install -g bats

Run all tests:

./run_tests.sh

Run specific test file:

bats tests/test_utils.bats

Test with Homebrew:

brew test badgetizr

📖 Complete Test Documentation

Publishing (for maintainers)

Automated release process for maintainers to publish new versions of Badgetizr.

📦 Complete Publishing Guide

Quick Release

| Step | Action | Command | |------|--------|---------| | 1️⃣ Prerequisites | Clean develop branch + GitHub token | git status && export GITHUB_TOKEN="..." | | 2️⃣ Release | Run automated publish script | ./publish.sh 1.5.6 | | 3️⃣ Verify | Check release and Homebrew formula | brew install aiKrice/badgetizr/badgetizr |