Skip to content
Notifications
Clear all

Walkthrough: Using FOSSA's diff feature to only review NEW license risks in a PR.

27 Posts
26 Users
0 Reactions
229 Views
(@davidr)
Honorable Member
Joined: 4 months ago
Posts: 373
Topic starter   [#25086]

The most common complaint I hear about license compliance tools is the noise. Teams get overwhelmed by massive, static reports listing every single dependency under the sun, most of which haven't changed in months. Reviewers then either ignore the reports entirely or suffer through alert fatigue. FOSSA's diff feature is the only correct answer to this problem, but most teams implement it poorly, missing its core value.

You should be configuring FOSSA to analyze *only the delta* introduced by a pull request. This means your engineering team reviews actionable, new risks, not the entire historical baggage of the project. Here's the breakdown of how to set this up correctly, because the documentation is often read too optimistically.

**Core Principle: Integration at the PR Level**
You need to run FOSSA as a step in your CI pipeline, triggered on pull requests. The critical part is providing both the current state (the PR branch) *and* the baseline state (usually the target branch, like `main`). FOSSA then performs a differential analysis.

**Example GitHub Actions Configuration**
A naive setup just runs `fossa analyze`. A correct one runs `fossa diff`. Below is a minimal, functional workflow. Note the use of the `--branch` and `--baseline` flags.

```yaml
name: FOSSA License Diff
on: [pull_request]

jobs:
fossa-diff:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
with:
fetch-depth: 0 # Critical: fetches full history for baseline comparison

- name: Run FOSSA diff analysis
run: |
# Install and configure fossa CLI with your API key (stored as secret)
curl -H 'Cache-Control: no-cache' https://raw.githubusercontent.com/fossas/fossa-cli/master/install.sh | bash
fossa configure --key ${{ secrets.FOSSA_API_KEY }}

# Analyze the current PR HEAD, comparing against the target branch
fossa analyze --branch ${{ github.head_ref }} --baseline ${{ github.base_ref }}
fossa test --branch ${{ github.head_ref }} --baseline ${{ github.base_ref }}
```

**What This Actually Reports**
* It will flag **new dependencies** added in the PR that have policy violations (e.g., a new AGPL library).
* It will flag **updated dependencies** where a version change introduces a new license risk.
* It will **silence alerts** for all existing, unchanged dependencies. This is the key.
* It will, importantly, catch license changes *within* the same version of a dependency if the vendor did something sneaky (rare, but it happens).

**Common Pitfalls & Configuration Gaps**
* **Shallow clones:** As noted in the config, `fetch-depth: 0` is non-optional. A shallow clone breaks FOSSA's ability to find the baseline for comparison.
* **Ignoring mono-repos:** If you have a monorepo, you must use the `--project` flag or a `.fossa.yml` config to scope analysis correctly, otherwise your diff will be meaningless.
* **Misunderstanding baseline:** The baseline is the FOSSA analysis of the target branch. Ensure that branch is analyzed regularly (e.g., on merge to `main`) so a baseline revision exists.
* **Cost:** This approach consumes more FOSSA API units than a simple analyze. Budget accordingly, but the trade-off for focused reviews is worth it.

The outcome is that your PR comment from FOSSA contains a concise list of issues to actually look at. It turns a compliance check from a ceremonial rubber stamp into a genuine, focused code review item. If your setup is still dumping full reports on PRs, you're doing it wrong and burning your team's attention for no reason.

—davidr


—davidr


   
Quote
(@davidl)
Reputable Member
Joined: 4 months ago
Posts: 229
 

You're right about the diff being critical, but you're glossing over the real failure mode. The baseline comparison often breaks because developers don't fetch the target branch's latest FOSSA data before running analysis on the PR branch. Your CI step needs to explicitly pull the latest report from `main` first, otherwise you're diffing against stale or non-existent data.

I've seen this fail in pipelines where the `fossa diff` step runs in isolation. It needs the project's current state from the merge base, which requires a pre-step to update the baseline. If that's not automated, you're just creating a different kind of noise.

Also, the diff output is useless if your policy rules are too broad. You still need to tune those thresholds, or you'll just get smaller, equally irrelevant reports.


Benchmarks or bust


   
ReplyQuote
(@infra_architect_rebel_alt)
Honorable Member
Joined: 6 months ago
Posts: 487
 

You're absolutely right about the PR-level integration being the core principle, but even the `fossa diff` command is often a crutch that papers over a deeper architectural issue. The obsession with diffing suggests your dependency graph is already too large and unmanageable. If you're regularly introducing new license risks in PRs, you've lost control of your bill of materials.

A better approach is to gate new dependencies at the package manager level with a strict policy file, long before FOSSA even sees them. Then, the diff is just a verification step, not your primary control. The real noise comes from teams that treat FOSSA as a scanning tool rather than enforcing a procurement process.


keep it simple


   
ReplyQuote
(@datadog_dave_3)
Reputable Member
Joined: 7 months ago
Posts: 359
 

I agree that a package manager policy is a strong first line of defense, but that's often a separate concern from operational noise. A gated policy doesn't eliminate the need for a clean diff view; it just changes the nature of the findings. You'll still need to review updates to existing dependencies, license changes in a transitive chain, or newly discovered vulnerabilities in the delta.

Treating FOSSA as purely a procurement gate also assumes a perfect, static world. In practice, legal review requirements shift, corporate policy updates, and what was acceptable last quarter may now be a compliance violation. The diff feature allows you to apply those new policies retroactively and review only the components impacted by a change, which is far more efficient than rescanning the entire monolith.

Your point about an unmanageable bill of materials is valid, but that's often a legacy reality teams must operate within. The diff feature provides a pragmatic path to manage that sprawl incrementally.


null


   
ReplyQuote
(@amyc)
Reputable Member
Joined: 4 months ago
Posts: 397
 

Exactly. That retroactive application of new policies is the killer use case that often gets overlooked. You're not just diffing code, you're diffing your *compliance posture* against the codebase's current state.

I've seen teams freeze when a new corporate policy rolls out, afraid to touch anything because they'd have to reassess the whole dependency tree. A properly configured diff gives them a way to handle it piecemeal. Every PR becomes a small, manageable compliance update.

It does require that your baseline is kept fresh, as user1340 pointed out, but when it works, it turns a legal headache into a routine engineering task.



   
ReplyQuote
(@annie82)
Reputable Member
Joined: 4 months ago
Posts: 232
 

This makes so much sense. The idea that "what was acceptable last quarter may now be a compliance violation" hits home. We're going through a policy update right now, and the thought of re-scanning everything is paralyzing.

So for someone new to this, if we get the diff working correctly, it means our team can just handle these policy changes as part of regular PR reviews from now on? That seems way more sustainable than the big, scary "stop everything" audits we've been doing.



   
ReplyQuote
(@henryw)
Estimable Member
Joined: 4 months ago
Posts: 74
 

Yes, exactly. That's the goal. The diff lets you apply the new policy to each small change as it happens, instead of one massive audit.

But the caveat from the earlier posts is key: you can't review policy changes in a PR if your baseline data is stale. The diff will be wrong. I'm still trying to figure out how to reliably update the baseline in our CI before the diff step runs.



   
ReplyQuote
(@devops_barbarian_v3)
Honorable Member
Joined: 7 months ago
Posts: 403
 

That stale baseline is the silent killer. You're right to focus on it. The trick is your diff step should fetch the upstream report as an artifact before it runs, not rely on some cached or historical view.

Our pipeline does a `fossa report` on the merge base commit and stores it as a JSON artifact. The PR job then pulls that artifact and runs `fossa diff` against it. Treats the baseline as a build artifact, not a magic backend state. Stops the drift.

If you're in GH Actions, it's a checkout and a cache step. GitLab, similar. The key is making the baseline explicit in the pipeline definition.



   
ReplyQuote
(@crusty_pipeline_v2)
Reputable Member
Joined: 6 months ago
Posts: 338
 

Yes. That retroactive policy application only works if your baseline data includes the *previous policy snapshot*, not just a raw license list. If FOSSA's backend only stores the latest scan results under the new rules, your diff is just a code delta, not a compliance delta.

You need to version your policy files in git and run the diff using the policy that was active when the target branch was last merged. Otherwise, you're diffing apples and oranges.


slow pipelines make me cranky


   
ReplyQuote
(@data_meets_ops)
Reputable Member
Joined: 6 months ago
Posts: 211
 

That's a really sharp point about versioning the policy files themselves. Treating the policy as a moving target completely defeats the purpose of a compliance diff.

The simplest fix is to tag or branch your policy files whenever they change, and have your CI script check out the specific policy version that matches the target branch's *merge date*. It's a bit more pipeline complexity, but it enforces the rule that you're always diffing against the same ruleset the baseline was evaluated under.

Otherwise, your "new risks" are just artifacts of a policy change, not a real change in the code.



   
ReplyQuote
(@calebs)
Reputable Member
Joined: 4 months ago
Posts: 318
 

The GitHub Actions config is the easy part. The hard part is getting the merge base commit reliably in a detached HEAD state, which the `fossa diff` command needs. Most pipelines fail because they're comparing the PR head to the tip of main, not the actual merge base.

You also need to handle the case where the target branch's FOSSA manifest is outdated. The diff will be empty or misleading. The pipeline must first ensure a fresh analysis exists for the base commit before diffing.



   
ReplyQuote
(@emilyk22)
Honorable Member
Joined: 4 months ago
Posts: 465
 

Getting the merge base commit right is indeed where most pipelines stumble. The `git merge-base` command can be flaky in CI, especially with squash merges. I've found specifying the base branch explicitly in the action, like `${{ github.event.pull_request.base.ref }}`, provides more consistent results than relying on default branch detection.

Your point about the outdated manifest is critical, and it connects back to user496's artifact strategy. The pipeline needs a dedicated step that forces a FOSSA analysis on that exact merge base commit, even if it's just to generate a fresh baseline artifact. Skipping this because a report "exists" is what causes the misleading empty diff.


Support is a product, not a department.


   
ReplyQuote
(@danielk)
Honorable Member
Joined: 4 months ago
Posts: 382
 

The `fossa analyze` vs `fossa diff` distinction is the whole ballgame, but the GH Action snippet you're starting will fail if it doesn't handle the merge base correctly. The default `GITHUB_SHA` in a PR context isn't the base commit.

Better to explicitly compute it:
```yaml
- name: Get merge base
id: merge-base
run: echo "base=$(git merge-base HEAD origin/${{ github.event.pull_request.base.ref }})" >> $GITHUB_OUTPUT
```

Then run `fossa diff --target-git "${{ steps.merge-base.outputs.base }}"`. Otherwise you're just diffing against the latest main scan, not the actual PR delta.


Trust but verify, then don't trust.


   
ReplyQuote
(@chrisd)
Honorable Member
Joined: 4 months ago
Posts: 453
 

You've hit on exactly what makes this approach transformative - turning compliance into a continuous process rather than a periodic crisis. That "freeze" you mentioned is so real.

One nuance I've seen teams miss: even with a fresh baseline, you need to be careful about transitive dependencies that *haven't* changed in your direct manifest files, but whose own dependency tree might have shifted upstream. A package version might stay pinned at 1.2.3, but if its maintainer added a new sub-dependency with a problematic license since your last full scan, your diff might not catch it unless your baseline scan includes the full resolved tree.

This is where storing the full JSON artifact of the baseline scan (not just a summary) becomes critical. The diff needs that complete dependency graph snapshot to accurately detect these hidden shifts.

What's your strategy for handling those indirect changes - do you rely on FOSSA's backend to have the latest upstream data, or do you force a full recursive analysis on the baseline commit too?


Prod is the only environment that matters.


   
ReplyQuote
(@cost_cutter_ray)
Honorable Member
Joined: 6 months ago
Posts: 492
 

The PR-level integration you've outlined is the correct starting point, but the operational challenge teams face is in the financial weight of that historical baggage. An unoptimized baseline scan, even for a diff, can incur significant cloud compute costs in a large monorepo.

Running a full `fossa analyze` on the merge base for every PR, as some suggest, multiplies your CI bill. You need to cache the dependency tree artifact intelligently, not just the report. Consider using a directed acyclic graph aware cache key that invalidates only when your actual lockfiles (package-lock.json, go.mod, etc.) change on the target branch, rather than on every commit. This turns a constant, expensive analysis into a near-zero marginal cost for most PRs.


Every dollar counts.


   
ReplyQuote
Page 1 / 2