Automatic Updates
Keep FOSSA projects continuously scanned, re-analyze on every new revision and surface new license and security issues automatically.
Overview
FOSSA can re-build a project automatically whenever its code changes; because an issue scan runs after every build, new license and security issues surface without anyone starting a build by hand. You control how each project updates, who gets notified, whether results gate your CI builds, and how status is reported back in your repository.
How automatic updates work
- New commits trigger a build. For a project connected to a repository (GitHub, GitLab, Bitbucket Cloud, Azure Repos) or a CI provider, an update hook tells FOSSA when a new revision lands, and FOSSA re-builds (re-analyzes) it. An issue scan runs after each build, so new license and security issues surface automatically. FOSSA configures this hook for you when you import the project through an integration (Quick Import).
- CLI-analyzed projects update from your pipeline. Projects you upload with the FOSSA CLI don't use update hooks; each CLI upload is itself the signal to re-analyze.
- Issue scans also re-run on their own. Beyond builds, FOSSA re-checks a project's existing dependencies for new issues whenever FOSSA's vulnerability data is updated or your policies change, so newly disclosed vulnerabilities surface even without a new commit.
- A Scheduled hook re-builds the project revision on a timer. You can optionally have a project re-build on a fixed schedule; as with any build, an issue scan runs afterward.
Enabling automatic updates for a project
- 1
Open the project's Hooks settings
From your project, go to Settings → Hooks.
- 2
Choose how updates are triggered
Pick a hook type from the dropdown; it defaults to No Automatic Updates. The repository option matching the project's host (for example GitHub) appears alongside the host-independent options Scheduled, Webhook, CircleCI, and TravisCI. See Update hook types below.
- 3
Finish provider setup
For a repository host (GitHub, GitLab, and so on) FOSSA configures the webhook on your repo for you. For Scheduled, set the interval and time. For Webhook, CircleCI, or TravisCI, copy the generated Update URL and have your pipeline ping it.
Projects imported via Quick Import already have a matching hook configured. Open Settings → Hooks to confirm or change it. Projects uploaded with the FOSSA CLI don't use update hooks; each CLI upload is itself the signal to re-analyze.
A project uses one hook at a time. Switching a repository-connected project to a Scheduled hook stops commit-triggered builds. Keep the repository hook if you want a build on every push.
Admins can set an org-wide default schedule under Account Settings → Projects → Hooks and use Propagate to apply it to existing projects.
Update hook types
The hook types offered in Settings → Hooks depend on the project's version control host, only the repository option matching that host appears.
| Hook type | What it does |
|---|---|
| No Automatic Updates | FOSSA doesn't re-build the revision on its own. A build happens only when you upload one from the CLI or trigger it manually (shown as "Manual Updates"). |
| Scheduled | Re-builds the project revision on a recurring schedule you set (interval and time). An issue scan runs after each build. |
| GitHub / GitLab / Bitbucket Cloud / Azure Repos | Triggers a build when a new revision is pushed to the connected repository. FOSSA configures the repository webhook for you. |
| CircleCI / TravisCI | Triggers a build when your CI pipeline pings the FOSSA update URL for that provider. |
| Webhook | Provides a generic update URL, pinging it triggers a build. Use this for any CI system without a dedicated option, such as Jenkins. |
Gating CI builds on FOSSA results
You can make your build react to FOSSA's findings in two complementary ways.
From CI with fossa test
If you run the FOSSA CLI in your pipeline, add fossa test after fossa analyze. It waits for the scan to finish and exits non-zero when the project has issues, failing the build. See the CLI docs and the integrations for wiring it into specific CI systems.
GitHub status checks
For GitHub projects, FOSSA can report a status check on every pull request and block merges when new issues are detected. See Pull Request Checks for setup and configuration.
Embedding a status badge
From your project, go to Settings → General and find the Embed Status Badge panel. Choose a badge type (License Shield, Security Shield (when Security is enabled), Small, or Large) then copy the Markdown, HTML, or Link snippet into your README or documentation.
Note
If you want FOSSA to add the badge to your README automatically at import time rather than copying it manually, see Badge Pull Requests. That option is available for public GitHub repositories during Quick Import.
Managing who gets notified
When an automatic scan finds a new issue, FOSSA emails the project's subscribed users. You can manage the recipient list in the UI or through the API.
| Scope | Where in the UI | API reference |
|---|---|---|
| Organization-wide default (applied to new projects) | Account Settings → Projects → Notifications | PUT /organizations/{id}/settings/projects/notifications |
| A single project | The project's Settings → Notifications | PUT /projects/{locator} |
| Look up user IDs | GET /users |
Setting the organization default. Send the recipient list with notificationDefaultEmailScanUserType set to custom and the FOSSA user IDs in notificationDefaultEmailScanUsers, or use all or current to let FOSSA fill the list for you. This request replaces the entire settings object, so fetch the current values first (a GET to the same path) and send them back together with your changes.
Warning
Older integrations set default recipients by PUTting notification_default_email_scan_users directly to /organizations/{id}. Use the project notification settings endpoint instead.
Setting recipients on one project. Update the project's notifications array, giving each entry a channel of SCAN, a service (EMAIL, SLACK, or API_WEBHOOK), and the subscribed_users IDs. Use the project locator without a revision.
Finding user IDs. Recipient lists are arrays of FOSSA user IDs. List your organization's users to map people to their IDs. Run it as an org admin to get the complete list.
FAQ
Can I use FOSSA with Jenkins, Azure Pipelines, or another CI system that isn't in the list? Yes. Either run fossa analyze and fossa test as steps in your pipeline, or choose the Webhook hook type and have your build ping its update URL. The dropdown only lists first-class options; anything else integrates through the CLI or a generic webhook.
If I put a project on a schedule, will it catch new issues each time? Usually only when something has actually changed. A scheduled hook re-builds the project revision and runs an issue scan afterward, but FOSSA already re-checks for issues after every commit-triggered build and whenever FOSSA's vulnerability data is updated or your policies change, and it emails about an issue only the first time it's found. A fixed schedule rarely surfaces anything those automatic scans haven't already caught.
Why isn't my project updating automatically? Open Settings → Hooks and confirm the hook type isn't No Automatic Updates. Projects uploaded with the FOSSA CLI don't use hooks, they update when your CI re-runs the analysis. New repository projects get a hook automatically on import.
Which repository hosts can trigger a build on push? GitHub, GitLab, Bitbucket Cloud, and Azure Repos. The Hooks dropdown shows only the option matching your project's host.
How do I change who gets emailed about new issues? Set the recipient list under Account Settings → Projects → Notifications (the organization-wide default) or in a project's Settings → Notifications, or automate it through the API. See Managing who gets notified.
What's next
- Pull Request Checks: Block merges when automatic scans detect new issues using status checks.
- Scan Frequency: Schedule recurring scans to catch newly disclosed vulnerabilities even without code changes.
- Notifications: Manage who gets notified when automatic scans find new issues.