How to Integrate OSV-Scanner with GitHub Actions: Complete Setup Guide

The quickest way to integrate OSV-Scanner with GitHub Actions is by invoking the reusable workflows from google/osv-scanner-action, which wrap a Docker-based action and automatically upload SARIF results to GitHub Code Scanning.

The google/osv-scanner repository provides a production-ready GitHub Action that enables continuous vulnerability scanning directly within your CI/CD pipelines. To integrate OSV-Scanner with GitHub Actions workflows, you reference reusable workflow definitions that handle repository checkout, scanner execution, and Security tab publication with minimal configuration.

Architecture of the OSV-Scanner GitHub Action

The integration relies on a containerized action defined in the source repository, consumed through wrapper workflows hosted separately.

actions/scanner/action.yml defines the Docker-based action metadata. It declares a single input scan-args (multi-line string) that splits into separate CLI arguments passed directly to the osv-scanner binary.

action.dockerfile builds the runtime environment. It starts from a minimal Go runtime image, installs the osv-scanner binary, and sets the entrypoint to execute the CLI in an isolated, reproducible container.

Reusable workflows in the companion repository google/osv-scanner-action provide two orchestration patterns:

• osv-scanner-reusable-pr.yml – Runs on pull requests and merge groups, comparing the PR’s changes against the target branch to detect newly introduced vulnerabilities.
• osv-scanner-reusable.yml – Performs full repository scans on pushes, schedules, or releases, scanning the complete codebase (or specified subsets).

Both workflows forward your inputs to the core action and handle SARIF artifact upload to GitHub Code Scanning, requiring only security-events: write permission.

Setting Up PR-Based Vulnerability Scanning

To block merges that introduce known vulnerabilities, use the PR reusable workflow. This runs osv-scanner scan source --recursive ./ against the PR diff and uploads results.sarif to the Security tab.

Create .github/workflows/osv-scanner-pr.yml in your repository:

name: OSV-Scanner PR Scan

on:
  pull_request:
    branches: [main]
  merge_group:
    branches: [main]

permissions:
  actions: read
  security-events: write
  contents: read

jobs:
  scan-pr:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@v2.3.4"

• on: pull_request triggers the scan when PRs target the main branch.
• on: merge_group ensures the scan runs before merging via GitHub's merge queue.
• Permissions are minimal: read access to contents and actions, write access only to security events for SARIF upload.

Configuring Scheduled and Push-Based Scanning

For continuous monitoring of the default branch, use the full scan reusable workflow. This performs a comprehensive vulnerability audit on every push and on a defined schedule.

Create .github/workflows/osv-scanner-scheduled.yml:

name: OSV-Scanner Scheduled Scan

on:
  schedule:
    - cron: "30 12 * * 1"    # Every Monday at 12:30 UTC

  push:
    branches: [main]

permissions:
  actions: read
  security-events: write
  contents: read

jobs:
  scan-scheduled:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable.yml@v2.3.4"

• schedule runs the workflow asynchronously (e.g., weekly) to catch new vulnerabilities in existing dependencies.
• push ensures immediate feedback when code changes land on the default branch.

Customizing Scan Arguments and Behavior

The reusable workflows expose inputs that forward directly to the osv-scanner CLI via the scan-args parameter. Customize the scan scope, severity thresholds, or output formats without modifying the underlying action.

jobs:
  scan-pr:
    uses: "google/osv-scanner-action/.github/workflows/osv-scanner-reusable-pr.yml@v2.3.4"
    with:
      scan-args: |-
        --lockfile=./path/to/package-lock.json
        --severity-threshold=high
        --recursive
      fail-on-vuln: true
      upload-sarif: true

• scan-args accepts any valid OSV-Scanner CLI flags documented in the project's usage guide.
• fail-on-vuln: true causes the workflow to exit with an error code if vulnerabilities are found, blocking PR merges or breaking scheduled builds.
• upload-sarif controls whether results appear in the GitHub Security > Code Scanning UI; disable for debugging or private fork scans.

Summary

• Use osv-scanner-reusable-pr.yml to scan pull requests and prevent vulnerable code from merging.
• Use osv-scanner-reusable.yml for scheduled or push-based full repository audits.
• Configure permissions with contents: read and security-events: write to allow SARIF upload without excessive access.
• Customize via scan-args to target specific lockfiles or filter by severity using standard CLI flags.
• Reference version tags (e.g., @v2.3.4) in the uses: statement to control updates and ensure reproducible builds.

Frequently Asked Questions

What file permissions does the OSV-Scanner GitHub Action require?

The action requires three specific permissions: contents: read to check out your repository, actions: read to access workflow artifacts if needed, and security-events: write to upload the SARIF report to GitHub Code Scanning. These are read-only for code and write-only for security events, following the principle of least privilege.

Can I scan only specific lockfiles or directories instead of the entire repository?

Yes, pass custom arguments through the scan-args input. For example, set scan-args: --lockfile=./frontend/package-lock.json --no-recursive to limit the scan to a specific manifest file, or specify paths like ./src to constrain the scan scope as implemented in the underlying CLI.

How does the PR scan workflow differ from the scheduled scan workflow?

The PR reusable workflow (osv-scanner-reusable-pr.yml) performs a differential scan comparing the PR branch against the target base, reporting only new vulnerabilities introduced by the changes. The scheduled workflow (osv-scanner-reusable.yml) performs a full scan of the entire repository state, suitable for detecting newly disclosed vulnerabilities in existing dependencies.

Where are the vulnerability results displayed after the workflow runs?

Results are automatically uploaded as SARIF artifacts to the Security > Code Scanning tab of your GitHub repository, provided you have not disabled upload-sarif. The action generates a results.sarif file that GitHub parses to create alerts with severity levels and remediation links directly in the pull request checks and security dashboard.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}