GitHub Integration

GitHub Integration

Ossprey integrates with GitHub via a GitHub App to automatically scan your repositories for malicious packages. This section covers how to connect, configure, and manage the integration.


Why connect GitHub?

Connecting your GitHub account enables automatic scanning on pull requests, continuous monitoring without manual intervention, easy setup with no CLI installation or configuration files required, and organisation-wide coverage — install once and scan across all your repos without requiring individual developers to change their workflows.


Connecting GitHub

Step 1: Navigate to GitHub Integrations

Click GitHub Integrations in the sidebar menu.

Step 2: Install the Ossprey GitHub App

    Click Connect GitHub
    You'll be redirected to GitHub
    Select the organisation or personal account you want to connect
    Choose repository access — All repositories (current and future) or Selected repositories (choose specific repos to monitor)
    Click Install to complete the setup
The Ossprey GitHub App requests read access to your repository metadata and package manifests. It accesses your repository content to generate SBOMs, but does not store your source code.

Step 3: Verify the connection

After installation, you'll be redirected back to Ossprey. Your connected account will appear on the GitHub Integrations page showing the account/organisation name, number of accessible repositories, and connection status.

Step 4: Test with a single repository

Before enabling all your repositories, we recommend starting with one repo. Navigate to GitHub Monitoring in the sidebar, enable scanning for a single repository, and confirm a scan completes successfully. Once you're satisfied, expand to additional repositories.


Managing repositories

Viewing installations

The GitHub Integrations page shows all connected accounts with their repository count, monitoring status, and connection health.

Adding more accounts

Click Connect GitHub again to add additional organisations or accounts.

Modifying access

To change which repositories Ossprey can access:
    Go to your GitHub account settings
    Navigate to Applications → Installed GitHub Apps
    Find Ossprey and click Configure
    Update repository access as needed

Configuring repository monitoring

Navigate to GitHub Monitoring in the sidebar to configure how your repositories are scanned. For each repository, you can toggle scanning on or off, choose which branch to monitor (default: main/master), set a subdirectory path to scan, and configure a scan schedule (daily, weekly).

https://slite.com/api/files/ff3QL3wWHoOyIM/image.png?apiToken=eyJhbGciOiJIUzI1NiIsImtpZCI6IjIwMjMtMDUtMDQifQ.eyJzY29wZSI6Im5vdGUtZXhwb3J0IiwibmlkIjoiRW9ocXJ1azRPUnhpLUYiLCJpYXQiOjE3Nzc3MzMyNjUsImlzcyI6Imh0dHBzOi8vc2xpdGUuY29tIiwianRpIjoiV0tWVDVfNkdiZmdVUkoiLCJleHAiOjE3ODAzMjUyNjV9.av6zRRxs_YDXnl1ML0eTS9Xi0sEwIZRq3gUFXPHklVE

Adding public repositories

You can also monitor public repositories that you don't own. Navigate to GitHub Monitoring, click Add Public Repository, enter the owner/organisation and repository name, configure monitoring settings, and save. Public repositories are accessed via GitHub's public API and don't require app installation.


How scans work

Your repositories are scanned in the following scenarios:
  • On pull request — when a PR is opened or updated against the monitored branch (results appear as PR checks)
  • On schedule — based on your configured scan schedule
  • Manually — when you request a new scan from the dashboard
Ossprey analyses your package manifest files (e.g. package.json, requirements.txt, poetry.lock) to build an SBOM of your dependency tree, then scans each package for known malware. Scan results appear on the Scan Results page, organised by organisation/repository.
PIC-TODO: Screenshot of a GitHub pull request showing an Ossprey inline review comment flagging a malicious package, plus the PR check status (pass/fail).
PIC-TODO: Graphic — a simple flow diagram showing: PR Opened → SBOM Generated → Packages Scanned → Verdict Returned → PR Check Posted. Could be a Mermaid diagram or a designed graphic.


Troubleshooting the integration

Repository not appearing

  • Verify Ossprey has access to the repository in GitHub Settings → Applications → Installed GitHub Apps
  • Check that the repository isn't empty
  • Ensure the repository has a supported package manifest (package.json, requirements.txt, etc.)

Scans not running

  • Confirm the repository is enabled in GitHub Monitoring
  • Check that you're opening PRs against the monitored branch
  • Verify your account is in good standing

Connection issues

  • Try disconnecting and reconnecting the GitHub app
  • Check GitHub's status page for any ongoing issues
  • Check that your organisation allows third-party apps
  • Contact support if problems persist