RepoLens

A CLI tool to audit GitHub repositories for best practices, security, and compliance.

Features

• Audit repositories for security issues and best practices
• Detect exposed secrets and credentials
• Check for required files (README, LICENSE, CONTRIBUTING, etc.)
• Validate GitHub workflows and Actions
• Verify license compliance across dependencies
• Generate actionable fix plans
• Apply fixes automatically or with dry-run mode
• Multiple output formats: terminal, JSON, SARIF, Markdown, HTML

Installation

Docker (Recommended)

The easiest way to use RepoLens without local installation:

# Pull the official image
docker pull ghcr.io/delfour-co/repolens:latest

# Audit current directory
docker run --rm -v "$(pwd)":/repo ghcr.io/delfour-co/repolens plan

# Generate a report
docker run --rm -v "$(pwd)":/repo ghcr.io/delfour-co/repolens report --format json

See docs/docker.md for detailed Docker usage.

Package Managers

Homebrew (macOS/Linux)

brew tap delfour-co/repolens
brew install repolens

Scoop (Windows)

scoop bucket add delfour-co https://github.com/delfour-co/scoop-bucket
scoop install repolens

AUR (Arch Linux)

yay -S repolens

From crates.io

cargo install repolens

Pre-built Binaries

Pre-built binaries are available for all major platforms. Download the latest release from the Releases page.

Supported Platforms

Linux (x86_64)

curl -LO https://github.com/delfour-co/cli--repolens/releases/latest/download/repolens-linux-x86_64.tar.gz
tar xzf repolens-linux-x86_64.tar.gz
sudo mv repolens /usr/local/bin/

Linux (ARM64)

curl -LO https://github.com/delfour-co/cli--repolens/releases/latest/download/repolens-linux-arm64.tar.gz
tar xzf repolens-linux-arm64.tar.gz
sudo mv repolens /usr/local/bin/

macOS (Apple Silicon)

curl -LO https://github.com/delfour-co/cli--repolens/releases/latest/download/repolens-darwin-arm64.tar.gz
tar xzf repolens-darwin-arm64.tar.gz
sudo mv repolens /usr/local/bin/

macOS (Intel)

curl -LO https://github.com/delfour-co/cli--repolens/releases/latest/download/repolens-darwin-x86_64.tar.gz
tar xzf repolens-darwin-x86_64.tar.gz
sudo mv repolens /usr/local/bin/

Windows (x86_64)

# Download the zip archive from the Releases page
Invoke-WebRequest -Uri https://github.com/delfour-co/cli--repolens/releases/latest/download/repolens-windows-x86_64.zip -OutFile repolens-windows-x86_64.zip
Expand-Archive repolens-windows-x86_64.zip -DestinationPath .
Move-Item repolens.exe C:\Users\$env:USERNAME\bin\

Verify Checksums

Each release includes a checksums.sha256 file. After downloading your archive, verify its integrity:

# Download the checksums file
curl -LO https://github.com/delfour-co/cli--repolens/releases/latest/download/checksums.sha256

# Verify (Linux)
sha256sum -c checksums.sha256 --ignore-missing

# Verify (macOS)
shasum -a 256 -c checksums.sha256 --ignore-missing

Verify Installation

repolens --version

From Source

# Clone repository
git clone https://github.com/kdelfour/repolens.git
cd repolens

# Build
cargo build --release

# The binary will be at target/release/repolens

Nightly Builds

Nightly builds are available for testing. See the Releases page for nightly builds (marked as pre-release).

Warning: Nightly builds may be unstable. Use at your own risk.

Docker

RepoLens is available as a Docker image for easy deployment:

# Pull the latest image
docker pull ghcr.io/delfour-co/cli--audit-github-project:latest

# Run on current directory
docker run --rm -v "$(pwd)":/repo ghcr.io/delfour-co/cli--audit-github-project plan

# Generate a report
docker run --rm -v "$(pwd)":/repo ghcr.io/delfour-co/cli--audit-github-project report

For GitHub API access, mount your GitHub CLI config:

docker run --rm \
  -v "$(pwd)":/repo \
  -v ~/.config/gh:/home/repolens/.config/gh:ro \
  ghcr.io/delfour-co/cli--audit-github-project plan

See docs/docker.md for detailed Docker usage instructions.

Prerequisites

RepoLens requires the following tools to be installed and configured:

When running repolens init, these prerequisites are automatically verified:

Checking prerequisites...

  ✓ Git installed
  ✓ Git repository
  ✓ GitHub CLI installed
  ✓ GitHub CLI authenticated
  ✓ Remote origin configured
  ✓ Remote is GitHub

If a required prerequisite fails, you'll see an error with a suggested fix:

  ✗ GitHub CLI installed
    GitHub CLI (gh) is not installed
    Fix: Install gh: https://cli.github.com/

Use --skip-checks to bypass prerequisite verification (not recommended).

Usage

Initialize Configuration

# Create default configuration
repolens init

# Use a preset
repolens init --preset opensource
repolens init --preset enterprise
repolens init --preset strict

# Skip prerequisite checks (not recommended)
repolens init --skip-checks

Run Audit

# Generate audit plan
repolens plan

# Audit a different directory
repolens -C /path/to/project plan

# Output in different formats
repolens plan --format json
repolens plan --format sarif
repolens plan --format markdown

# Verbose mode with timing information
repolens plan -v      # Basic timing
repolens plan -vv     # Detailed timing per category
repolens plan -vvv    # Debug level

Apply Fixes

# Preview changes (shows diff without applying)
repolens apply --dry-run

# Apply all fixes with confirmation prompt
repolens apply

# Interactive mode: select actions individually with diff preview
repolens apply --interactive
repolens apply -i

# Auto-accept all actions without confirmation
repolens apply --yes
repolens apply -y

# Apply specific categories only
repolens apply --only files,docs

# Skip specific categories
repolens apply --skip security

Interactive Mode

The interactive mode (-i or --interactive) provides an enhanced user experience:

1. Visual Summary: Displays a categorized overview of all planned actions
2. Action Selection: Use MultiSelect to choose which actions to apply (Space to toggle, Enter to confirm)
3. Diff Preview: Shows a colored diff (green for additions, red for deletions) for each selected action
4. Progress Bar: Displays real-time progress during execution
5. Execution Summary: Shows detailed results with success/failure counts

Example output:

==============================================================================
                     ACTION SUMMARY
==============================================================================

[F] GITIGNORE (1 action)
    + Update .gitignore with recommended entries
      - .env
      - *.key

[F] FILES (2 actions)
    + Create CONTRIBUTING.md from template
    + Create SECURITY.md from template

==============================================================================
  Total: 3 actions to apply
==============================================================================

Generate Report

# Terminal report
repolens report

# Export report
repolens report --format html --output report.html

# JSON report with JSON Schema reference
repolens report --format json --schema

# JSON report with schema validation
repolens report --format json --schema --validate

JSON Schema

RepoLens provides a JSON Schema (draft-07) that describes the structure of the JSON audit report output. This enables validation of report output and integration with tools that consume JSON Schema.

# Display the JSON Schema on stdout
repolens schema

# Save the JSON Schema to a file
repolens schema --output schemas/audit-report.schema.json

The schema defines the following structure:

• repository_name: Name of the audited repository
• preset: Audit preset used (opensource, enterprise, strict)
• findings: Array of audit findings, each with:
  • rule_id: Unique rule identifier (e.g., SEC001)
  • category: Finding category (secrets, files, docs, security, workflows, quality)
  • severity: Severity level (critical, warning, info)
  • message: Description of the finding
  • location: Optional file location
  • description: Optional detailed description
  • remediation: Optional suggested fix
• metadata: Report metadata (version, timestamp, schema_version)
• summary: Aggregated counts by severity and category

When using --schema, the JSON output includes a $schema field referencing the schema URI. When using --validate, the output is validated against the schema before being emitted.

Comparing Audits

Compare two previously generated JSON audit reports to visualize improvements and regressions between runs.

# First, generate two JSON reports at different points in time
repolens report --format json --output report-before.json
# ... make changes ...
repolens report --format json --output report-after.json

# Compare the two reports (terminal output with colors)
repolens compare --base-file report-before.json --head-file report-after.json

# Output as JSON
repolens compare --base-file report-before.json --head-file report-after.json --format json

# Output as Markdown
repolens compare --base-file report-before.json --head-file report-after.json --format markdown

# Save comparison to a file
repolens compare --base-file report-before.json --head-file report-after.json --output comparison.md --format markdown

# Fail with exit code 1 if new issues are detected (useful in CI)
repolens compare --base-file baseline.json --head-file current.json --fail-on-regression

The comparison report includes:

• Score summary: Weighted score (Critical=10, Warning=3, Info=1) with diff
• New issues: Findings present in the head report but not in the base (regressions)
• Resolved issues: Findings present in the base report but not in the head (improvements)
• Category breakdown: Per-category count changes

Configuration

Create a .repolens.toml file in your repository root:

[general]
preset = "opensource"

[rules]
secrets = true
files = true
docs = true
security = true
workflows = true
quality = true

[files.required]
readme = true
license = true
contributing = true
code_of_conduct = true
security = true

Custom Rules

Define your own audit rules using regex patterns or shell commands:

# Detect TODO comments
[rules.custom."no-todo"]
pattern = "TODO"
severity = "warning"
files = ["**/*.rs"]
message = "TODO comment found"

# Check git status (shell command)
[rules.custom."check-git-status"]
command = "git status --porcelain"
severity = "warning"
invert = true  # Fail if uncommitted changes
message = "Working directory is not clean"

Security Warning: Custom rules with shell commands execute arbitrary code on your system. Only use commands from trusted sources. Never commit or run .repolens.toml files from untrusted repositories without reviewing them first.

See the Custom Rules documentation for more examples and details.

Cache

RepoLens includes a caching system to improve performance by avoiding re-auditing files that haven't changed. Cache entries are automatically invalidated when file content changes (detected via SHA256 hashing).

Cache Configuration

[cache]
# Enable/disable caching (default: true)
enabled = true
# Maximum age for cache entries in hours (default: 24)
max_age_hours = 24
# Cache directory (relative to project root or absolute path)
directory = ".repolens/cache"

Cache CLI Options

# Disable cache and force a complete re-audit
repolens plan --no-cache

# Clear the cache before running the audit
repolens plan --clear-cache

# Use a custom cache directory
repolens plan --cache-dir /tmp/repolens-cache

The same options are available for the report command.

### Environment Variables

RepoLens can be configured via environment variables. Priority order: CLI flags > Environment variables > Config file > Defaults.

| Variable | Description | Example |
|----------|-------------|---------|
| `REPOLENS_PRESET` | Default preset to use | `enterprise` |
| `REPOLENS_VERBOSE` | Verbosity level (0-3) | `2` |
| `REPOLENS_CONFIG` | Path to config file | `/path/to/.repolens.toml` |
| `REPOLENS_NO_CACHE` | Disable caching | `true` |
| `REPOLENS_GITHUB_TOKEN` | GitHub token for API calls | `ghp_xxx` |

```bash
# Example usage
export REPOLENS_PRESET=enterprise
export REPOLENS_VERBOSE=2
repolens plan

Exit Codes

RepoLens uses standard exit codes for CI/CD integration:

# Example usage in CI/CD
repolens plan
case $? in
  0) echo "All clear!" ;;
  1) echo "Critical issues found - blocking release" && exit 1 ;;
  2) echo "Warnings found - review recommended" ;;
  3) echo "Error running audit" && exit 1 ;;
  4) echo "Invalid arguments" && exit 1 ;;
esac

Git Hooks

RepoLens can install Git hooks to automatically check your code before commits and pushes.

Install Hooks

# Install all configured hooks (pre-commit + pre-push)
repolens install-hooks

# Install only the pre-commit hook
repolens install-hooks --pre-commit

# Install only the pre-push hook
repolens install-hooks --pre-push

# Force overwrite existing hooks (backs up originals)
repolens install-hooks --force

Remove Hooks

# Remove all RepoLens hooks (restores backups if they exist)
repolens install-hooks --remove

Hook Behavior

• pre-commit: Scans staged files for exposed secrets before each commit. If secrets are detected, the commit is aborted.
• pre-push: Runs a full audit before pushing. If issues are found, the push is aborted.

Both hooks can be bypassed with --no-verify (e.g., git commit --no-verify).

Configuration

Configure hooks in .repolens.toml:

[hooks]
# Install pre-commit hook (checks for exposed secrets)
pre_commit = true
# Install pre-push hook (runs full audit)
pre_push = true
# Whether warnings should cause hook failure
fail_on_warnings = false

When fail_on_warnings is true, hooks will also fail on warning-level findings, not just critical issues.

Presets

Rules Categories

• secrets: Detect exposed API keys, tokens, passwords
• files: Check for required repository files
• docs: Documentation completeness and quality
• security: Security best practices, branch protection (SEC007-010)
• workflows: CI/CD and GitHub Actions validation
• quality: Code quality standards
• licenses: License compliance checking (LIC001-LIC004)
• dependencies: Vulnerability scanning via OSV API (DEP001-003)
• git: Git hygiene rules (GIT001-003)

Git Hygiene Rules

Branch Protection Rules

Dependency Rules

Supported Ecosystems

RepoLens supports vulnerability scanning for multiple ecosystems:

License Compliance Rules

RepoLens can detect and verify license compliance for your project and its dependencies:

Supported dependency files:

• Cargo.toml (Rust)
• package.json / node_modules/*/package.json (Node.js)
• requirements.txt (Python)
• go.mod (Go)

Configure allowed and denied licenses in .repolens.toml:

["rules.licenses"]
enabled = true
allowed_licenses = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "ISC"]
denied_licenses = ["GPL-3.0", "AGPL-3.0"]

GitHub Action

RepoLens is available as a GitHub Action to integrate repository auditing directly into your CI/CD workflows.

Basic Usage

name: RepoLens Audit
on: [push, pull_request]

jobs:
  audit:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: kdelfour/repolens@main
        with:
          preset: 'opensource'
          format: 'terminal'
          fail-on: 'critical'

Inputs

Outputs

SARIF Integration

Upload results to GitHub Advanced Security for visibility in the Security tab:

- uses: kdelfour/repolens@main
  id: audit
  with:
    format: 'sarif'
    fail-on: 'none'

- uses: github/codeql-action/upload-sarif@v3
  if: always()
  with:
    sarif_file: ${{ steps.audit.outputs.report-path }}
    category: 'repolens'

PR Comment

Post audit results as a comment on pull requests. See the full example in examples/github-action/pr-comment.yml.

More Examples

See the examples/github-action/ directory for complete workflow examples:

• basic.yml -- Basic usage on push and pull requests
• sarif-upload.yml -- SARIF upload for GitHub Security
• pr-comment.yml -- Post results as a PR comment

CI/CD Integration

RepoLens integrates with all major CI/CD platforms. See docs/ci-cd-integration.md for detailed guides.

Contributing

See CONTRIBUTING.md for guidelines.

Development

See DEVELOPMENT.md for development setup, architecture, and contribution guidelines.

License

MIT License - see LICENSE for details.