Depscheck

A CI/CD tool for checking dependency license compatibility in Elixir projects.

Depscheck helps ensure your project's dependencies have compatible licenses by reading license information from local hex_metadata.config files and checking them against your project's license.

Features

• ✅ Offline Operation - No API calls needed, reads from local hex metadata files
• ✅ Fast - Completes in under a second for most projects
• ✅ Smart - Built-in license compatibility rules based on industry standards
• ✅ Simple - Zero configuration needed for basic usage
• ✅ CI/CD Ready - Exit codes and clear output for pipeline integration

Installation

Add depscheck to your list of dependencies in mix.exs:

def deps do
  [
    {:depscheck, "~> 1.0.11", only: [:dev, :test], runtime: false}
  ]
end

Usage

Basic Usage

Run the Mix task:

mix depscheck

Example output:

Checking licenses for MyProject (MIT)...

✓ jason (Apache-2.0) - Compatible
✓ plug (Apache-2.0) - Compatible
✓ phoenix (MIT) - Compatible
✗ some_gpl_package (GPL-3.0) - INCOMPATIBLE

Found 1 license violation(s)

Violations:
  • some_gpl_package (GPL-3.0): Strong copyleft license GPL-3.0 cannot be used in permissive project

Configuration

Create a .depscheck.exs file in your project root to ignore specific packages or override the project license:

%{
  ignored_packages: ["some_package", "another_package"],
  project_license: "All Rights Reserved"  # Override project license
}

Project License Override

You can override the project license detected from mix.exs by setting project_license in your configuration:

# .depscheck.exs
%{
  project_license: "All Rights Reserved"  # Treat as proprietary
}

This is useful for:

• Proprietary projects that don't declare a license in mix.exs
• Testing different license scenarios
• Explicit declaration of proprietary status

CI/CD Integration

Depscheck exits with code 0 on success and 1 on failure, making it perfect for CI/CD pipelines. When violations are found, the command will fail and stop your CI pipeline.

GitHub Actions

Use the provided workflow file (.github/workflows/license_check.yml):

name: License Check

on:
  push:
    branches: [ main, master ]
  pull_request:
    branches: [ main, master ]

jobs:
  check-licenses:
    name: Check Dependency Licenses
    runs-on: ubuntu-latest
    
    steps:
      - name: Checkout code
        uses: actions/checkout@v4
      
      - name: Set up Elixir
        uses: erlef/setup-beam@v1
        with:
          elixir-version: '1.18.0'
          otp-version: '27.0'
      
      - name: Restore dependencies cache
        uses: actions/cache@v4
        with:
          path: deps
          key: ${{ runner.os }}-mix-${{ hashFiles('**/mix.lock') }}
          restore-keys: ${{ runner.os }}-mix-
      
      - name: Install dependencies
        run: mix deps.get
      
      - name: Check dependency licenses
        run: mix depscheck

Or add it to an existing workflow:

- name: Check dependency licenses
  run: mix depscheck

GitLab CI

license_check:
  stage: test
  script:
    - mix deps.get
    - mix depscheck
  rules:
    - if: '$CI_PIPELINE_SOURCE == "merge_request_event"'
    - if: '$CI_COMMIT_BRANCH == "main"'

CircleCI

- run:
    name: Check dependency licenses
    command: |
      mix deps.get
      mix depscheck

Exit Codes

• 0 - All dependencies are compatible (CI passes ✅)
• 1 - License violations found (CI fails ❌)

How It Works

1. Reads your project license from mix.exs
2. Reads dependency licenses from deps/*/hex_metadata.config files (downloaded by mix deps.get)
3. Checks compatibility using built-in license compatibility rules
4. Reports violations with clear, actionable messages

License Compatibility

Depscheck implements industry-standard license compatibility rules:

• Permissive licenses (MIT, Apache-2.0, BSD) are compatible with everything
• Weak copyleft licenses (LGPL, MPL) are compatible with most open source projects
• Strong copyleft licenses (GPL, AGPL) require your entire project to be compatible
• Proprietary projects can only use permissive dependencies (legally safe)

Proprietary Projects

For projects without a license (proprietary/closed source), Depscheck:

• Warns when no license is declared: "Project has no license - treating as proprietary"
• Only allows permissive dependencies (MIT, Apache-2.0, BSD, etc.)
• Blocks copyleft dependencies (GPL, LGPL, MPL) - legally incompatible
• Blocks unlicensed dependencies - you have no legal right to use them

Warnings

Depscheck provides helpful warnings for:

• Unlicensed projects - reminds you that no license = proprietary
• Unlicensed dependencies - warns about legal risks
• License compatibility issues - explains why certain combinations don't work

For detailed information about license compatibility rules, see LICENSE_COMPATIBILITY_RULES.md.

API Usage

You can also use Depscheck programmatically:

# Check all dependencies
result = Depscheck.check()

# Get project license
license = Depscheck.project_license()

# Get all dependencies
deps = Depscheck.dependencies()

Supported Licenses

Permissive

• MIT
• Apache-2.0
• BSD-2-Clause, BSD-3-Clause
• ISC
• Unlicense

Weak Copyleft

• LGPL-2.1, LGPL-3.0
• MPL-2.0
• EPL-2.0
• CDDL-1.0

Strong Copyleft

• GPL-2.0, GPL-3.0
• AGPL-3.0

Proprietary

• All Rights Reserved
• Unlicensed
• Proprietary

Unknown licenses are treated as compatible (warning only).

Development

Running Tests

mix test

Running Quality Checks

mix precommit  # Runs format, test, credo, and dialyzer

Releasing

To bump the version and prepare for release:

mix version patch  # or minor, or major

Inspiration

This project was inspired by hex_licenses. The approach of reading license information from local hex_metadata.config files (rather than making API calls) was adapted from that project. Thank you to the team for making this pattern available!

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Links

• License Compatibility Rules - Detailed explanation of compatibility logic
• hex_licenses - Inspiration for this project