Skip to content

Getting Started with OSS Sustain Guard

OSS Sustain Guard is a multi-language package sustainability analyzer that helps you understand the health of your dependencies. This guide shows you how to get started in just a few minutes.

📦 Installation

If you're not a Python developer or want to avoid polluting your global Python environment, use one of these methods:

Using pipx (recommended for most users):

# Install pipx first (if not already installed)
python3 -m pip install --user pipx
python3 -m pipx ensurepath

# Install oss-sustain-guard in isolated environment
pipx install oss-sustain-guard

Using uv tool (fastest option):

# Install uv first (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install oss-sustain-guard in isolated environment
uv tool install oss-sustain-guard

Using Docker (no Python installation needed):

# Pull the Docker image
docker pull ghcr.io/onukura/oss-sustain-guard:latest

# Run analysis (pass GitHub token as environment variable)
docker run --rm -e GITHUB_TOKEN=$GITHUB_TOKEN ghcr.io/onukura/oss-sustain-guard:latest check requests

Using GitHub Actions (for CI/CD):

- uses: onukura/oss-sustain-guard@main
  with:
    github-token: ${{ secrets.GITHUB_TOKEN }}

See GitHub Actions Guide for more details.

Standard Installation (for Python developers)

Install directly from PyPI:

pip install oss-sustain-guard

Quick Demo (No Token Needed)

Run the built-in demo data to see output instantly without network calls:

os4g check --demo

Demo data is a snapshot for illustration and may differ from current repository status.

🔐 GitHub and GitLab Token Setup (Required for Real-Time Analysis)

OSS Sustain Guard requires a GitHub Personal Access Token for most real-time analyses; a GitLab token is only needed when the source is hosted on gitlab.com.

This is needed because the tool fetches repository data directly from the host API to analyze:

  • Contributor activity and redundancy
  • Release patterns and commit history
  • Issue/PR response times
  • Security policies and funding information
  • And more sustainability metrics

GitHub Token Setup (3 steps)

1. Create a token: Visit https://github.com/settings/tokens/new and create a classic token with public_repo and security_events scopes.

2. Set the environment variable:

# Linux/macOS
export GITHUB_TOKEN='your_token_here'

# Windows PowerShell
$env:GITHUB_TOKEN='your_token_here'

# Or add to .env file in your project
echo "GITHUB_TOKEN=your_token_here" > .env

3. Verify it works:

os4g check requests

GitLab Token Setup (3 steps)

1. Create a token: Visit https://gitlab.com/-/user_settings/personal_access_tokens and create a token with read_api and read_repository scopes.

2. Set the environment variable:

# Linux/macOS
export GITLAB_TOKEN='your_token_here'

# Windows PowerShell
$env:GITLAB_TOKEN='your_token_here'

# Or add to .env file in your project
echo "GITLAB_TOKEN=your_token_here" > .env

3. Verify it works:

os4g check <package-hosted-on-gitlab>

Why is this required?

  • Unauthenticated API access has very low rate limits
  • Authenticated requests get higher limits and consistent access
  • Package analysis requires multiple API calls per repository

Security: Use minimal scopes (public_repo/security_events for GitHub, read_api/read_repository for GitLab). Never commit tokens to version control.

🚀 First Steps

1. Analyze Your Project's Dependencies (Most Common)

os4g check --include-lock

Automatically scans requirements.txt, package.json, Cargo.toml, and other manifest files to analyze all your project's dependencies.

Displays health scores of all packages with:

  • Health Score (0-100): Overall sustainability rating
  • Health Status: Healthy ✓, Monitor, or Needs support
  • Key Observations: Important signals about each project

2. Check a Single Package

os4g check requests

Analyze a specific package in detail.

3. Check Multiple Packages

os4g check python:django npm:react rust:tokio

Mix any languages you use in one command.

New ecosystems with package mode:

# Java (Maven coordinates: groupId:artifactId:version)
os4g check java:junit:junit:4.13.2 java:org.slf4j:slf4j-api:1.7.36

# C# (NuGet package names)
os4g check csharp:Newtonsoft.Json csharp:Serilog

# Dart (pub.dev package names)
os4g check dart:http dart:flutter_bloc

# Mix and match ecosystems
os4g check python:requests java:junit:junit:4.13.2 csharp:Newtonsoft.Json dart:http

4. Scan Entire Projects (Monorepos)

os4g check --recursive

Recursively finds and analyzes all dependencies in subdirectories.

See Dependency Analysis Guide for details (experimental).

📊 Understanding Scores

Your results show:

  • 🟢 80+: Healthy - Good state, continue monitoring
  • 🟡 50-79: Monitor - Review regularly for changes
  • 🔴 <50: Needs support - Consider support or migration

🎯 Common Scenarios

Evaluate a New Library

os4g check library-name --output-style detail

The --output-style detail (or -o detail) shows all metrics in a detailed table format.

For verbose logging (cache operations, metric reconstruction):

os4g check library-name -v

Check Your Project's Dependencies

cd /path/to/project
os4g check --include-lock

Use Different Scoring Profiles

Recalculate scores based on your priorities:

# Security-focused evaluation
os4g check requests --profile security_first

# Contributor-experience focused
os4g check requests --profile contributor_experience

# Long-term stability focused
os4g check requests --profile long_term_stability

Bypass Cache (Real-time Analysis)

os4g check requests --no-cache

Visualize Your Dependency Network

Create an interactive graph of your project's dependencies and their health scores:

# Generate an interactive HTML dependency graph
os4g graph package.json

# Export as JSON for integration with other tools
os4g graph Cargo.lock --output deps.json

# Expoer as HTML file
os4g graph uv.lock --output my-dependencies.html

See Dependency Graph Visualization Guide for more options.

Analyze how a repository's sustainability score changes over multiple time periods:

# Default: 6 monthly periods, 30-day windows
os4g trend requests

# Custom periods and intervals
os4g trend requests --periods 12 --interval weekly
os4g trend requests --periods 4 --interval quarterly --window-days 90

# Analyze recent history with daily granularity
os4g trend requests --periods 30 --interval daily --window-days 7

See Trend Analysis Guide for details on time-dependent metrics and visualization.

🔐 Token Setup (GitHub or GitLab)

Required: OSS Sustain Guard needs a token for the host where the repository lives.

GitHub (github.com)

  1. Create a token:

  2. Visit: https://github.com/settings/tokens/new

  3. Token name: oss-sustain-guard
  4. Select scopes: ✓ public_repo, ✓ security_events

  5. Click "Generate token" and copy it immediately

  6. Set the token:

Linux/macOS:

bash export GITHUB_TOKEN='your_token_here'

Windows (PowerShell):

powershell $env:GITHUB_TOKEN='your_token_here'

Persistent (recommended):

Add to your .env file in your project directory:

shell GITHUB_TOKEN=your_token_here

  1. Verify:

bash os4g check requests

GitLab (gitlab.com)

  1. Create a token:

  2. Visit: https://gitlab.com/-/user_settings/personal_access_tokens

  3. Token name: oss-sustain-guard
  4. Select scopes: ✓ read_api, ✓ read_repository

  5. Click "Create personal access token" and copy it immediately

  6. Set the token:

Linux/macOS:

bash export GITLAB_TOKEN='your_token_here'

Windows (PowerShell):

powershell $env:GITLAB_TOKEN='your_token_here'

Persistent (recommended):

Add to your .env file in your project directory:

shell GITLAB_TOKEN=your_token_here

  1. Verify:

bash os4g check <package-hosted-on-gitlab>

Why is a token needed?

The host API requires authentication for repository analysis. The token allows OSS Sustain Guard to:

  • Query repository metadata (contributors, releases, issues)
  • Access funding information
  • Analyze project health metrics

Rate Limits: With a token, you get higher rate limits than unauthenticated requests. Local caching minimizes API calls.

Security: Your token is only stored locally and never sent anywhere except the host API.

📚 Next Steps

Metric Description
Contributor Redundancy Distribution of contributions (lower = single-maintainer concentration)
Recent Activity Project's current activity level
Release Rhythm Release frequency and consistency
Commit Author Continuity Are the project's principal committers still active?
Community Health Issue response time and responsiveness

🔧 Useful Options

Output Formats

Control how results are displayed:

# Compact output (one line per package, ideal for CI/CD)
os4g check requests -o compact

# Normal output (default, table with key observations)
os4g check requests -o normal

# Detail output (full metrics table with all signals)
os4g check requests -o detail

Verbose Logging

Enable detailed logging for debugging and cache operations:

# Show cache operations and metric reconstruction
os4g check requests -v

# Combine with any output style
os4g check requests -v -o compact
os4g check requests -v -o detail

Use a Different Scoring Profile

Recalculate scores based on different priorities:

# Prioritize security
os4g check requests --profile security_first

# Prioritize contributor experience
os4g check requests --profile contributor_experience

# Prioritize long-term stability
os4g check requests --profile long_term_stability

Bypass Cache (Real-time Analysis)

os4g check requests --no-cache

📌 Next Steps

❓ Questions or Issues?

For help, see Troubleshooting & FAQ.

🌍 Supported Languages

Package Mode (Direct Resolution)

These ecosystems support direct package resolution from registries:

  • Python (PyPI via uv) - python:package or just package
  • JavaScript/TypeScript (npm) - javascript:package or npm:package
  • Rust (crates.io) - rust:package
  • Ruby (RubyGems) - ruby:package
  • Go (Go Modules) - go:github.com/user/repo
  • PHP (Packagist) - php:vendor/package
  • Java (Maven Central) - java:groupId:artifactId:version
  • C#/.NET (NuGet) - csharp:PackageName
  • Dart (pub.dev) - dart:package

Lockfile Mode

All languages support dependency analysis from lockfiles:

Python, JavaScript, TypeScript, Rust, Dart, Elixir, Haskell, Perl, R, Swift, Java, PHP, Ruby, C#, .NET, Go, Kotlin