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

> Integrate OSV-Scanner with GitHub Actions seamlessly. Learn how to leverage reusable workflows for automatic SARIF result uploads to GitHub Code Scanning. Get the complete setup guide.

- Repository: [Google/osv-scanner](https://github.com/google/osv-scanner)
- Tags: how-to-guide
- Published: 2026-04-25

---

**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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/.github/workflows/osv-scanner-pr.yml) in your repository:

```yaml
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`](https://github.com/google/osv-scanner/blob/main/.github/workflows/osv-scanner-scheduled.yml):

```yaml
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.

```yaml
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`](https://github.com/google/osv-scanner/blob/main/osv-scanner-reusable-pr.yml)** to scan pull requests and prevent vulnerable code from merging.
- **Use [`osv-scanner-reusable.yml`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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`](https://github.com/google/osv-scanner/blob/main/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.