Home

Welcome to the debtbomb wiki!

🧨 DebtBomb Wiki

Welcome to the DebtBomb wiki! DebtBomb is a cross-language technical-debt enforcement tool that scans source code comments for time-limited "debt bombs" and fails CI when they expire.

📋 Table of Contents

1. Introduction
2. Installation
3. Syntax Guide
4. CLI Reference
5. Configuration
6. Integrations
7. Ignoring Files
8. CI/CD Integration

---

Introduction

DebtBomb helps engineering teams manage technical debt by giving it a deadline. Instead of vague TODO comments that rot forever, DebtBomb requires an expiration date, an owner, and a reason. When the date passes, the build fails, forcing the team to either fix the debt or consciously extend the deadline.

---

Installation

Using Go

go install github.com/jobin-404/debtbomb/cmd/debtbomb@latest

From Source

git clone https://github.com/jobin-404/debtbomb.git
cd debtbomb
go build -o debtbomb cmd/debtbomb/main.go

---

Syntax Guide

DebtBomb scans comments for the @debtbomb tag. It supports both single-line and multi-line formats.

Single-line Format

Best for quick annotations.

// @debtbomb(expire=2026-02-10, owner=pricing, ticket=JIRA-123)

Note: Both : and = are supported as separators (e.g., expire:2026-02-10).

Multi-line Format

Best for detailed explanations.

# @debtbomb
#   expire: 2026-02-10
#   owner: backend
#   ticket: JIRA-123
#   reason: Temporary hack for migration

Supported Fields

Field	Required	Format	Description
expire	Yes	YYYY-MM-DD	The date when the debt expires.
owner	No	String	Person or team responsible.
ticket	No	String	Reference to an issue tracker.
reason	No	String	Why this debt exists.

---

CLI Reference

debtbomb check

The primary command for CI enforcement.

• debtbomb check: Fails (exit code 1) if any bomb is expired.
• debtbomb check --warn-in-days 7: Warns about bombs expiring in the next 7 days.
• debtbomb check --json: Outputs results in JSON format.

debtbomb list

Lists all tracked debt bombs.

• debtbomb list: Shows a formatted table of all bombs.
• debtbomb list --expired: Shows only expired bombs.

debtbomb report

Generates high-level statistics.

• debtbomb report: Shows debt breakdown by owner, folder, reason, and urgency.

---

Configuration

Configure DebtBomb via .debtbomb/config.toml in your project root.

[jira]
default_project = "ENG"
issue_type = "Technical Debt"

[[notify]]
on = "expired"
via = "slack"

[[notify]]
on = "expiring_soon"
via = "slack"
days = 7

---

Integrations

DebtBomb supports Jira, Slack, Discord, and MS Teams.

Environment Variables

Variable	Description
JIRA_BASE_URL	Jira instance URL.
JIRA_EMAIL	Jira account email.
JIRA_API_TOKEN	Jira API token.
SLACK_WEBHOOK_URL	Slack Incoming Webhook.
DISCORD_WEBHOOK_URL	Discord Webhook URL.
TEAMS_WEBHOOK_URL	MS Teams Webhook URL.

---

Ignoring Files

Create a .debtbombignore file to exclude specific paths. It uses the same syntax as .gitignore.

# Ignore generated files
src/generated/
*.min.js

---

CI/CD Integration

GitHub Actions

name: Technical Debt Check
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Set up Go
        uses: actions/setup-go@v4
        with:
          go-version: '1.21'
      - name: Install DebtBomb
        run: go install github.com/jobin-404/debtbomb/cmd/debtbomb@latest
      - name: Run Check
        run: debtbomb check --warn-in-days 7