CI/CD and headless CLI

Use debtdrone scan in CI/CD pipelines and scripted workflows. Findings are written to stdout, analyzer warnings are written to stderr, and a configured quality gate returns a non-zero exit when its threshold is reached.

For a complete flag and subcommand inventory, use the command reference.

Run a scan

debtdrone scan [path] [flags]

The path defaults to the current directory.

Flag	Default	Description
--format	text	Output text or json
--fail-on	unset	Fail on critical, high, medium, or low findings
--max-complexity	15	Report high cyclomatic complexity above this value; critical starts above twice this value
--security-scan	true	Enable Trivy vulnerability scanning
--coverage	false	Parse existing coverage artifacts without running tests

Text output

debtdrone scan ./src --format=text --security-scan=false

Text output is a table with one row per finding:

SEVERITY   FILE:LINE                         RULE   MESSAGE
--------   ---------                         ----   -------
CRITICAL   /workspace/src/handler.go:112     N/A    Function 'ProcessRequest' has high cyclomatic complexity of 28 (threshold: 10)

If no findings are produced, the command prints:

No technical debt issues found.

JSON output

debtdrone scan ./src --format=json --security-scan=false

JSON output is an array of TechnicalDebtIssue objects. This abbreviated example shows the fields most commonly used in automation; actual objects also contain identifiers, status, confidence, timestamps, and optional context:

[
  {
    "file_path": "/workspace/src/handler.go",
    "line_number": 112,
    "issue_type": "complexity",
    "severity": "critical",
    "category": "complexity",
    "message": "Function 'ProcessRequest' has high cyclomatic complexity of 28 (threshold: 10)",
    "tool_name": "complexity_analyzer",
    "technical_debt_hours": 1.42
  }
]

Filter the array directly with jq:

# Print critical findings
debtdrone scan . --format=json --security-scan=false \
  | jq '.[] | select(.severity == "critical")'

# Sum estimated debt hours
debtdrone scan . --format=json --security-scan=false \
  | jq '[.[].technical_debt_hours] | add // 0'

Coverage and analyzer warnings remain on stderr, so stdout stays valid JSON.

Enforce a quality gate

--fail-on fails when a finding matches or exceeds the selected severity:

critical  ← most severe
high
medium
low       ← least severe

For example, --fail-on=high fails on high and critical findings:

debtdrone scan . --fail-on=high

Exit code	Meaning
0	Scan completed without a gate violation
1	The gate failed, input was invalid, or the scan completed with an analyzer error

If --fail-on is omitted, findings alone do not fail the command. Analyzer errors can still produce a non-zero exit. .debtdrone.yaml does not currently set a gate; pass the flag explicitly.

GitHub Actions example

name: Technical Debt Gate

on:
  pull_request:
    branches: [main]

jobs:
  debt-analysis:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v4

      - name: Set up Go
        uses: actions/setup-go@v5
        with:
          go-version: '1.25'

      - name: Install DebtDrone
        run: go install github.com/endrilickollari/debtdrone-cli/v2/cmd/debtdrone@latest

      - name: Run debt analysis
        run: debtdrone scan . --format=json --fail-on=high | tee debt-report.json

      - name: Upload debt report
        if: always()
        uses: actions/upload-artifact@v4
        with:
          name: debt-report
          path: debt-report.json

GitHub Actions enables pipeline failure propagation for the shell step, so a quality-gate error still fails the job while tee preserves stdout as an artifact.

Parse coverage artifacts

Coverage analysis is opt-in:

debtdrone scan . --coverage --format=json

The CLI discovers supported Go coverage, LCOV, Cobertura, JaCoCo, Clover, and SimpleCov files. It parses existing artifacts only; it does not run tests, package managers, build tools, or Docker. Missing or malformed artifacts produce warnings on stderr.

Configuration and history commands

• debtdrone init creates a .debtdrone.yaml template, but scans do not load that file yet.
• debtdrone config list, get, set, and unset manage the user-level versioned file. Headless scans apply those settings after environment values and before explicit command flags.
• debtdrone history list returns bounded persisted summaries in text or JSON. Use history show <id>, history delete <id>, and the confirmed history clear command to inspect or manage them.

See Configuration for paths, precedence, and validation. See Local history storage for the persistence and privacy contract. For common pipeline and analyzer failures, see Troubleshooting.