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

Platform	Architecture	Archive
Linux	x86_64	`repolens-linux-x86_64.tar.gz`
Linux	ARM64	`repolens-linux-arm64.tar.gz`
macOS	Intel x86_64	`repolens-darwin-x86_64.tar.gz`
macOS	Apple Silicon ARM64	`repolens-darwin-arm64.tar.gz`
Windows	x86_64	`repolens-windows-x86_64.zip`

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:

Tool	Required	Description
Git	Yes	Must be installed and the directory must be a git repository
GitHub CLI (gh)	Yes	Must be installed and authenticated (`gh auth login`)

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:

Visual Summary: Displays a categorized overview of all planned actions
Action Selection: Use MultiSelect to choose which actions to apply (Space to toggle, Enter to confirm)
Diff Preview: Shows a colored diff (green for additions, red for deletions) for each selected action
Progress Bar: Displays real-time progress during execution
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:

Code	Meaning	Example
0	Success	Audit completed, no critical issues
1	Critical issues	Secrets exposed, critical vulnerabilities
2	Warnings	Missing files, non-critical findings
3	Runtime error	File not found, network error
4	Invalid arguments	Unknown category, invalid preset

# 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

Preset	Description
`opensource`	Standard open-source requirements
`enterprise`	Enterprise security and compliance
`strict`	Maximum security and documentation

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

Rule	Severity	Description
GIT001	Warning	Large binary files detected (should use Git LFS)
GIT002	Info	`.gitattributes` file missing
GIT003	Warning	Sensitive files tracked (.env, .key, .pem, credentials)

Branch Protection Rules

Rule	Severity	Description
SEC007	Info	`.github/settings.yml` missing
SEC008	Warning	No branch protection rules in settings.yml
SEC009	Warning	`required_pull_request_reviews` not configured
SEC010	Warning	`required_status_checks` not configured

Dependency Rules

Rule	Severity	Description
DEP001	Critical/Warning	Vulnerability detected in dependency
DEP002	Warning	Outdated dependency version
DEP003	Warning	Lock file missing for detected ecosystem

Supported Ecosystems

RepoLens supports vulnerability scanning for multiple ecosystems:

Ecosystem	Manifest	Lock File	OSV Support
Rust (Cargo)	`Cargo.toml`	`Cargo.lock`	Yes
Node.js (npm)	`package.json`	`package-lock.json`	Yes
Python (pip/poetry)	`pyproject.toml`	`poetry.lock`	Yes
Go	`go.mod`	`go.sum`	Yes
.NET (NuGet)	`*.csproj`	`packages.lock.json`	Yes
Ruby (Bundler)	`Gemfile`	`Gemfile.lock`	Yes
Dart/Flutter (Pub)	`pubspec.yaml`	`pubspec.lock`	Yes
Swift (SPM)	`Package.swift`	`Package.resolved`	No
iOS (CocoaPods)	`Podfile`	`Podfile.lock`	No

License Compliance Rules

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

Rule	Severity	Description
LIC001	Warning	No project license detected
LIC002	Critical/Warning	Dependency license incompatible or not allowed
LIC003	Info	Dependency uses unknown/unrecognized license
LIC004	Warning	Dependency has no license specified

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

Input	Description	Default
`preset`	Audit preset (`opensource`, `enterprise`, `strict`)	`opensource`
`format`	Output format (`terminal`, `json`, `sarif`, `markdown`, `html`)	`terminal`
`fail-on`	Fail on severity level (`critical`, `high`, `medium`, `low`, `none`)	`critical`
`config`	Path to a custom `.repolens.toml` config file
`version`	RepoLens version to install (e.g. `1.0.0` or `latest`)	`latest`
`upload-artifact`	Upload report as a GitHub Actions artifact	`true`
`artifact-name`	Name of the uploaded artifact	`repolens-report`

Outputs

Output	Description
`report-path`	Path to the generated report file
`findings-count`	Total number of findings detected
`exit-code`	Exit code (`0`=success, `1`=critical, `2`=warnings)

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.

Platform	Template
GitHub Actions	integrations/github-actions/repolens.yml
GitLab CI	integrations/gitlab-ci/.gitlab-ci.yml
CircleCI	integrations/circleci/config.yml
Jenkins	integrations/jenkins/Jenkinsfile
Azure DevOps	integrations/azure-devops/azure-pipelines.yml

Contributing

See CONTRIBUTING.md for guidelines.

Development

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

License

MIT License - see LICENSE for details.

repolens 1.0.0

RepoLens

Features

Installation

Docker (Recommended)

Package Managers

Homebrew (macOS/Linux)

Scoop (Windows)

AUR (Arch Linux)

From crates.io

Pre-built Binaries

Supported Platforms

Linux (x86_64)

Linux (ARM64)

macOS (Apple Silicon)

macOS (Intel)

Windows (x86_64)

Verify Checksums

Verify Installation

From Source

Nightly Builds

Docker

Prerequisites

Usage

Initialize Configuration

Run Audit

Apply Fixes

Interactive Mode

Generate Report

JSON Schema

Comparing Audits

Configuration

Custom Rules

Cache

Cache Configuration

Cache CLI Options

Exit Codes

Git Hooks

Install Hooks

Remove Hooks

Hook Behavior

Configuration

Presets

Rules Categories

Git Hygiene Rules

Branch Protection Rules

Dependency Rules

Supported Ecosystems

License Compliance Rules

GitHub Action

Basic Usage

Inputs

Outputs

SARIF Integration

PR Comment

More Examples

CI/CD Integration

Contributing

Development

License