Skip to main content
The SCANOSS pre-commit hooks run just before your changes are committed, triggering automated scans to detect open-source components that have not been declared in your scanoss.json configuration. By catching undeclared components at commit time, issues are identified early in the development process rather than later in the pipeline.

​
Prerequisites

Before you begin, ensure the following are installed and configured:

​
Installation

pip install pre-commit

​
Getting Started

​
Configure the Hook

Create .pre-commit-config.yaml at the root of your repository: 
repos:
  - repo: https://github.com/scanoss/pre-commit-hooks
    rev: v0.4.0 # Use the latest version from https://github.com/scanoss/pre-commit-hooks/releases
    hooks:
      - id: scanoss-check-undeclared-code

​
Verify Configuration

pre-commit validate-config

​
Install the Hook

pre-commit install

​
Test the Hook

# Stage files to test
git add .

# Run hook against all files
pre-commit run --all-files

​
Configuration

​
Environment Variables

The hook automatically loads variables from a .env file in your project root: 
# .env
SCANOSS_API_KEY=your_api_key_here
SCANOSS_SCAN_URL=https://api.scanoss.com/scan/direct
HTTPS_PROXY=http://proxy.example.com:8080
SCANOSS_DEBUG=true

​
How It Works

​
Example Workflow

Given this project structure: 
my-project/
├── src/
│   ├── scanner.py
│   └── utils.c
├── .env
└── .pre-commit-config.yaml
When you commit: 
git add src/
git commit -m "Add new features"
The hook automatically:
  1. Scans staged files for open-source components.
  2. Compares detected components against the declarations in your scanoss.json file. A declaration is an explicit acknowledgement that a given open-source component is present and approved for use in your project.
  3. Blocks the commit if any undeclared components are found.

​
Example Output

The following is an example of output produced when undeclared components are detected. File paths and package identifiers are truncated for brevity. 
$ git commit -m "updating relevant files"
[WARNING] Unstaged files detected.
[INFO] Stashing unstaged files to ~/.cache/pre-commit/patch1763626421-7396.
SCANOSS Undeclared Check.................................................Failed
- hook id: scanoss-check-undeclared-code
- duration: 7.75s
- exit code: 1
- files were modified by this hook

SCANOSS detected 2 files containing potential open-source components:
┌──────────────┬─────────┬────────────┬─────────┬──────────────┬──────────────┐
│ File         │ Status  │ Match Type │ Matched │ Purl         │ License      │
├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤
│ src/copyrig… │ pending │ snippet    │ 95%     │ pkg:github/… │ GPL-2.0-only │
├──────────────┼─────────┼────────────┼─────────┼──────────────┼──────────────┤
│ src/scanner… │ pending │ snippet    │ 96%     │ pkg:github/… │ MIT          │
└──────────────┴─────────┴────────────┴─────────┴──────────────┴──────────────┘
Run 'scanoss-cc' in the terminal to view the results in more detail.

[WARNING] Stashed changes conflicted with hook auto-fixes... Rolling back fixes...
[INFO] Restored changes from ~/.cache/pre-commit/patch1763626421-7396.
Note: The files were modified by this hook message indicates that the hook wrote scan result metadata to your working directory as part of its analysis. These modifications are rolled back if a conflict with unstaged changes is detected, as shown in the output above.
The commit is blocked until you take one of the following actions:
  1. Declare the components in scanoss.json.
  2. Run scanoss-cc in the terminal to review and declare the components interactively.
  3. Remove the non-compliant or undeclared code.

​
Troubleshooting

​
Enable Debug Mode

Method 1: Environment Variable 
export SCANOSS_DEBUG=true
git commit -m "test"
Method 2: .env File 
# .env
SCANOSS_DEBUG=true
Method 3: Command-Line Argument 
repos:
  - repo: https://github.com/scanoss/pre-commit-hooks
    rev: v0.4.0
    hooks:
      - id: scanoss-check-undeclared-code
        args: ["--debug"]