Skip to content
Unentropy

Getting Started

Unentropy helps you track code metrics directly in your CI pipeline—without external servers, cloud dependencies, or vendor lock-in. Get started in under 2 minutes.

What You’ll Learn

Section titled “What You’ll Learn”

This guide shows you how to:

  • Generate a configuration file
  • Verify metrics collection locally
  • Add GitHub Actions workflows
  • View your first metrics report

1. Generate Configuration

Section titled “1. Generate Configuration”

Tip: Unentropy supports both npx and bunx

Run this command in your project directory:

npx unentropy init

Unentropy auto-detects your project type (JavaScript, PHP, Go, or Python) and creates unentropy.json with sensible defaults for tracking lines of code and test coverage.

Example configuration:

{
  "storage": {
    "type": "sqlite-artifact"
  },
  "metrics": {
    "lines-of-code": {
      "$ref": "loc",
      "command": "@collect loc ./src --language TypeScript"
    },
    "test-coverage": {
      "$ref": "coverage",
      "command": "@collect coverage-lcov ./coverage/lcov.info"
    }
  },
  "qualityGate": {
    "mode": "soft",
    "thresholds": [
      {
        "metric": "test-coverage",
        "mode": "min",
        "target": 80,
        "severity": "blocker"
      }
    ]
  }
}

This configuration tracks two metrics:

  • Lines of Code: Measures the size of your codebase by counting lines in the src/ directory
  • Test Coverage: Measures test coverage percentage from your coverage report

It also includes a quality gate that fails if test coverage drops below 80%, helping prevent coverage regressions in pull requests. Your metrics history will be stored in GitHub Actions workflow artifacts - this will get you up and running quickly, but may not be suitable for long-term tracking. See Storage Guide for more options.

Since no metrics are collected yet, the preview will show example, random-generated data.

Override Auto-Detection

Section titled “Override Auto-Detection”

If auto-detection picks the wrong type, specify it explicitly:

npx unentropy init --type php

Supported types: javascript, php, go, python

2. Preview Your Report

Section titled “2. Preview Your Report”

See what your metrics report will look like:

npx unentropy preview

This generates an HTML report with your configured metrics (showing empty data) and opens it in your browser. Use this to verify your setup before collecting real data.

3. Add GitHub Workflows

Section titled “3. Add GitHub Workflows”

Copy the workflow examples from your init output into your repository:

Main Branch Tracking

Section titled “Main Branch Tracking”

Create .github/workflows/metrics.yml:

name: Track Metrics
on:
  push:
    branches: [main]

permissions:
  contents: read # Required to checkout the code
  actions: read # Required to download artifacts
  pages: write # Required to publish reports
  id-token: write # Required to publish reports

jobs:
  track-metrics:
    runs-on: ubuntu-latest
    steps:
      # Checkout code, install dependencies, and run tests to generate coverage metrics
      # Adjust commands based on your project type
      - uses: actions/checkout@v6
      - name: Install dependencies
        run: bun install
      - name: Run tests with coverage
        run: bun test --coverage --coverage-reporter=lcov

      # Collect metrics
      - name: Track metrics
        uses: unentropy/track-metrics@v0

      # Optional: Publish metrics report to GitHub Pages
      - uses: actions/upload-pages-artifact@v3
        with:
          path: unentropy-report
      - name: Deploy to GitHub Pages
        uses: actions/deploy-pages@v4
        id: report_deployment

    environment:
      name: github-pages
      url: ${{ steps.report_deployment.outputs.page_url }}

Enable GitHub Pages in your repository settings to view reports at https://<username>.github.io/<repo>/.

Pull Request Quality Gate

Section titled “Pull Request Quality Gate”

Create .github/workflows/quality-gate.yml:

name: Quality Gate
on:
  pull_request:

permissions:
  contents: read
  actions: read
  pull-requests: write

jobs:
  quality-gate:
    runs-on: ubuntu-latest

    steps:
      # Adjust commands based on your project type
      - uses: actions/checkout@v6
      - name: Install dependencies
        run: bun install
      - name: Run tests with coverage
        run: bun test --coverage --coverage-reporter=lcov

      - name: Quality Gate Check
        uses: unentropy/quality-gate@v0

Commit and push these files to start tracking metrics.

That’s it! Metrics are now tracked automatically on every commit to main. Your metrics report will be published to your repository’s GitHub Pages, and quality gate feedback will be automatically posted as comments on pull requests.

What’s Next?

Section titled “What’s Next?”

Common Questions

Section titled “Common Questions”

Where is my data stored?

Section titled “Where is my data stored?”

By default, metrics are stored in GitHub Actions workflow artifacts (90-day retention). You can switch to S3-compatible storage for long-term history. See Storage Guide.

Do I need to run tests before collecting metrics?

Section titled “Do I need to run tests before collecting metrics?”

For coverage metrics, yes. Run your test suite with coverage reporting enabled (e.g., bun test --coverage --coverage-reporter=lcov) before collecting metrics. Other metrics like lines of code work without additional setup.

What if my project type isn’t detected?

Section titled “What if my project type isn’t detected?”

Use --type to specify it explicitly, or create unentropy.json manually following the Configuration Reference.

Section titled “Related Resources”