GitHub Actions Integration Guide

This guide explains how to integrate OSS Sustain Guard into your GitHub Actions workflows for automated package sustainability checks.

Overview

OSS Sustain Guard provides three ways to integrate with GitHub Actions:

1. Docker Action (Recommended) - Pre-built Docker image for fastest execution
2. Reusable Workflow (.github/workflows/check-packages.yml) - Shared workflow for multiple projects
3. Composite Action - Pure shell implementation (legacy)

Quick Start

The fastest and most reliable way to use OSS Sustain Guard:

- name: Check package sustainability
  uses: onukura/oss-sustain-guard@main
  with:
    packages: 'requests django flask'
    output-style: 'compact'

💡 Tip: For CI/CD, use the compact output format

Use output-style: 'compact' for cleaner workflow logs. This provides one-line-per-package output, perfect for logs and automated reporting.

1. Auto-Detect and Check All Repository Dependencies (Recommended)

The most common use case - automatically detect and analyze all dependencies in your repository:

name: Dependency Health Check

on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check all repository dependencies
        uses: onukura/oss-sustain-guard@main
        with:
          include-lock: 'true'
          output-style: 'compact'

Automatically detects from:

• package-lock.json / pnpm-lock.yaml / bun.lock / deno.lock (JavaScript)
• requirements.txt / poetry.lock / uv.lock (Python)
• Cargo.lock (Rust)
• Gemfile.lock (Ruby)
• composer.lock (PHP)
• go.sum (Go)
• And more...

2. Check Specific Priority Packages

For security audits or high-priority dependency reviews:

name: Priority Packages Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check priority dependencies
        uses: onukura/oss-sustain-guard@main
        with:
          packages: 'flask django requests'
          output-style: 'compact'

3. Fail on Needs Support Findings

name: Needs Support Dependencies Check

on: [pull_request]

jobs:
  security:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check low-scoring dependencies
        uses: onukura/oss-sustain-guard@main
        with:
          packages: 'core-payment-lib authentication-provider'
          verbose: 'true'

      - name: Review priority packages
        if: failure()
        run: echo "⚠️  Priority packages need review!"

4. Recursive Monorepo Scanning

For monorepo projects, recursively scan all subdirectories:

name: Monorepo Dependency Scan

on: [pull_request]

jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Scan all packages in monorepo
        uses: onukura/oss-sustain-guard@main
        with:
          recursive: 'true'
          root-dir: './packages'
          output-style: 'compact'

5. Specific Manifest File Analysis

Analyze a specific manifest file (useful for multiple environments):

name: Production Dependencies Check

on: [pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Check production dependencies
        uses: onukura/oss-sustain-guard@main
        with:
          manifest: './requirements/production.txt'
          profile: 'long_term_stability'
          output-style: 'detail'

FAQ

• Do I need a token?: Yes. GITHUB_TOKEN covers most repos; GITLAB_TOKEN is only needed for gitlab.com sources.
• Does it support multiple languages?: Yes! Python, JavaScript, Rust, Go, Ruby, PHP, and more are supported out of the box.
• How do I check only specific packages?: Use the packages input: packages: 'flask django npm:react'
• How do I skip the check?: Remove or comment out the step in your workflow.

For more details or troubleshooting, see the GitHub repository or Getting Started.

Performance Tips

Reuse cached data with GitHub Actions cache

You can speed up repeated runs by caching OSS Sustain Guard's local cache directory. Add a step before the scan to restore the cache:

    - name: Restore OSS Sustain Guard cache
      uses: actions/cache@v4
      with:
        path: ${{ env.OSS_SUSTAIN_GUARD_CACHE_DIR || '~/.cache/oss-sustain-guard' }}
        key: oss-sg-${{ runner.os }}-${{ github.run_id }}
        restore-keys: |
          oss-sg-${{ runner.os }}-

    # ...run OSS Sustain Guard scan here...

Customizing the cache location

By default, the cache directory is ~/.cache/oss-sustain-guard. You can control this location by setting the OSS_SUSTAIN_GUARD_CACHE_DIR environment variable in your workflow:

    - name: Set custom cache dir
      run: echo "OSS_SUSTAIN_GUARD_CACHE_DIR=$HOME/oss-sg-cache" >> $GITHUB_ENV

Then update the cache step to use the same path:

    - name: Restore OSS Sustain Guard cache
      uses: actions/cache@v4
      with:
        path: ${{ env.OSS_SUSTAIN_GUARD_CACHE_DIR }}
        # ...

This is useful if you want to isolate caches between jobs or workflows.

This ensures that package analysis results are reused between CI runs, making subsequent checks much faster and reducing API usage.

Security Considerations

1. Token scoping - Use read-only GitHub or GitLab tokens when possible
2. Sensitive packages - Don't expose internal package names in logs
3. PR comments - Be careful when posting results as PR comments

Support

For issues or questions:

• GitHub Issues
• Getting Started
• Documentation