Skip to main content
This guide is for teams that already use SCANOSS’s standalone tools and are moving to Earnie. It explains what replaces each tool, and walks you through the switch in five phases.
New to SCANOSS, with none of these tools set up? You don’t need this guide. Start with What is Earnie?, then Workspace setup.
The tools you use today each do one job, and you connect them yourself:
  • the scanoss/pre-commit-hooks pre-commit hook checks your code each time you commit
  • scanoss-py, a command-line scanner, scans your code on your own machine and saves the results in .scanoss/results.json
  • Code Compare, a desktop app, is where you review what the scan matched, and it saves your decisions in a file in your repository called scanoss.json
  • the SCANOSS code-scan GitHub Action scans each pull request and reports three checks on it
  • Dependency-Track, a separate open-source tool, holds your policies, the code that breaks them, and the exceptions you’ve allowed
Earnie does all of this in one place. You connect your repositories once. Earnie then scans them, checks what it finds against your organisation’s rules, and gives each pull request one check that either lets it merge or blocks it. The same rules apply wherever code changes: You move over in five phases:
  1. Connect and scan. Connect your repositories to Earnie and run a first scan.
  2. Bring over your identifications. Earnie reads the decisions already saved in your scanoss.json.
  3. Rebuild your policies. Recreate your Dependency-Track rules in Earnie.
  4. Switch the gate. Replace the old pull-request checks with Earnie’s, one repository at a time.
  5. Move developer tooling. Replace the pre-commit hook and install the Earnie CLI.
Until phase 4, your old tools keep checking your pull requests, so nothing changes for your developers. Earnie can’t compare its results with the old tools for you, so in phase 3 you check them yourself before you switch.

Key Terms

These words come up throughout the guide:

Before You Start

A few things the old tools did have no exact match in Earnie. Check these against your setup before phase 1:
  • CWE policies can’t be rebuilt. CWE is a list of software weakness types. Earnie has no CWE data, so a Dependency-Track rule based on CWE has no equivalent. See the policy table.
  • Policies don’t move over automatically. There’s no tool to import Dependency-Track policies, so you recreate them by hand in phase 3.
  • Each exception covers one finding. A component that shows up in many files needs a separate Policy Approval for each finding a policy flags.
  • You can’t limit a project to part of a repository. In a monorepo, use skip patterns to leave out the parts you don’t want scanned.
  • bom.ignore in scanoss.json isn’t applied. It hid matches from the results. Earnie shows those matches as findings for you to decide.

What Replaces What

Earnie also gives the same policies to AI coding agents, such as Claude Code or Cursor, while they write code. The old tools have nothing like this. See Earnie MCP.

The Five Phases

Each phase ends with a Done when check. Finish it before you start the next phase.

Phase 1: Connect and Scan

Set up your Earnie organisation, then connect your Git provider and import the repositories you want Earnie to check. Each repository becomes a project.
  • GitHub, including GitHub Enterprise Server, connects through the Earnie GitHub App.
  • GitLab, on gitlab.com or self-managed, connects with an access token.
To import a whole GitHub organisation or GitLab group in one go, select Import all repositories on Settings → Integrations. See Workspace setup and Connecting a repository. Done when: every project has one completed scan of its whole default branch (a full-coverage scan, not one of changed files only), and every connection on Settings → Integrations reads Healthy.
Expect a backlog on the first full scan. If the GitHub Action only ever scanned the files each pull request changed, nothing has checked your whole repository before. The first full scan can find things the old tools never showed you. That’s not a sign that something broke. Plan time to review them.

Phase 2: Bring Over Your Identifications

The decisions you made in Code Compare live in each repository’s scanoss.json. Earnie reads that file on every scan, so you don’t need to import it. Each kind of entry carries over like this: An entry applies only to a component the scan actually found, and an entry with a path applies only inside that path. An entry never adds a finding. Earnie names the scanoss.json file as the source of each decision it records this way. See Component overrides.
Confirming a component isn’t the same as accepting it. In Code Compare, including a component declared it, and that was enough to pass the “undeclared component” check. In Earnie, Confirm match only records that the match is real. The finding still counts towards your policies, so a copyleft policy still flags a confirmed GPL component. Only Mark original takes a finding out of the gate, and it means “this is our own code”, not “we accept this component”. To accept a real component that a policy flags, request a Policy Approval. See Violation States and Exceptions.
Decide what’s left in Earnie’s Review Workspace. In Components mode, Bulk decide records one decision for every undecided finding of a component at once. Done when: no project shows findings your team has already decided, and your reviewers agree that what’s left open is real work.

Phase 3: Rebuild Your Policies

Recreate your Dependency-Track policies as Earnie policies. Earnie can’t import them, because the two tools describe rules differently. Use the policy table to translate each rule, and Violation States and Exceptions to choose what each one does: Block, Require approval, or Warn. Where you can, start from Earnie’s built-in templates. They cover the rules most teams use, and they’re quicker to review than a rule you write yourself: Copyleft licences, such as the GPL, require you to share your own source code under the same licence in some cases. Weak copyleft licences, such as the LGPL, ask for less. Where your organisation has cryptography or AI provenance scanning, more templates are available. See Cryptography and AI provenance.
One copyleft policy becomes two. Dependency-Track has one Copyleft licence group. Earnie splits it into strong and weak copyleft, and the two templates act differently: strong copyleft requires approval, and weak copyleft only warns. If you turn on only the strong copyleft template, Earnie stops checking the weak copyleft licences you used to check, without telling you. Turn on both, or write one policy on the Copyleft field if you want them treated the same.
In Earnie, a policy belongs to your whole organisation, and you attach it to the projects it should check. A rule you had for one repository becomes a policy attached to one project. You can’t change a shared policy for just one project. To use a different rule there, clone the policy and change the copy. See Where a policy applies. Done when: for each project, Earnie’s gate gives the same result as Dependency-Track on the same code, or your policy owner has written down and accepted each difference. To compare, list the policies and what each one flags. These commands only read, and change nothing:

Phase 4: Switch the Gate

Your Git provider decides which checks must pass before a pull request can merge. On GitHub, this is branch protection, and each check it waits for is a required status check. In this phase, you make Earnie’s check the required one. For each repository, make these three changes together:
  1. In branch protection, add Earnie as a required status check.
  2. In branch protection, remove the three Policy Check: * required checks.
  3. In one pull request, delete the code-scan Action workflow and its Dependency-Track upload step, then merge it.
Make the branch-protection changes when you merge that pull request, not before or after. Branch protection waits for each check by its exact name. If a check is still required after you delete the workflow that sends it, every pull request waits for it forever. If both the old and new checks stay required, every pull request is checked twice. The Earnie check shows the gate like this: On a pull request, only the findings the pull request added decide the check. The summary comment also lists findings that were already on the default branch, but they don’t block the pull request. A neutral check means Earnie couldn’t compare, not that the pull request passed. It appears in two cases:
  • No baseline to compare against; result is not conclusive: Earnie has no completed scan of the default branch yet. Scan the default branch.
  • Base branch moved; result is not conclusive: the default branch has changed since the pull request was scanned. Push a commit, or run the scan again.
See When the check is neutral. An approval updates the pull request straight away. When an Admin grants a Policy Approval, Earnie updates the check and comments without a new push or scan. The check turns green only if the approval covers every finding that was holding the gate. Revoking an approval works the same way in reverse.
A pull request Earnie skips gets no check at all. A project can tell Earnie to skip draft pull requests, pull requests opened by bots, or pull requests outside chosen branches or paths. Earnie doesn’t scan those, so a required Earnie check never arrives and the pull request can’t merge. Either turn those settings off where Earnie is required, or agree that those pull requests merge without an Earnie check. See Choosing which pull requests Earnie checks.
On GitLab, Earnie can block a merge only on plans that support it, which today means GitLab Ultimate’s external status checks. See Merge blocking depends on your GitLab plan. Done when: in each repository, a pull request has merged with Earnie as the only required policy check, no workflow still runs the code-scan Action, and you’ve checked the pull-request skip settings in the repositories where Earnie is required.

Phase 5: Move Developer Tooling

Install the Earnie CLI wherever developers or pipelines need it:
Then sign in once with earnie auth login. See Earnie CLI. Replace the pre-commit hook. If your repositories use the pre-commit framework, replace the scanoss/pre-commit-hooks entry in .pre-commit-config.yaml:
Then run pre-commit install --install-hooks and pre-commit run earnie once, so the framework downloads and checks the pinned CLI before the first commit. If you don’t use the framework, run earnie hook install in each copy of the repository instead. Either way, the hook runs earnie scan staged --format hook on every commit. It checks the changes you’ve staged in Git, not every file you’ve edited, and runs a Self-check. A Self-check never adds findings to the project or changes its results. If the hook can’t run the check, for example because of a network or sign-in error, or because it took longer than 60 seconds, it reports the problem and lets the commit through. An Operator or Admin can make these failures stop the commit instead, with Pre-commit technical failures in the project’s Scan Configuration. A developer can do the same for their own commits by setting EARNIE_HOOK_FAIL_CLOSED=1. See When the Check Can’t Run in Checking before you commit. Optionally, connect AI coding agents. earnie mcp setup connects Claude Code, Cursor, VS Code, or Codex to Earnie, so the agents follow your policies while they write code. See Connecting an AI client. Finally, uninstall Code Compare. Done when: no repository’s developer instructions still mention scanoss/pre-commit-hooks, Code Compare, or scanoss-py, and a test commit in each repository shows up as a Self-check in Earnie.

Dependency-Track to Earnie Policies

Use this reference in phase 3, if you’re the person rebuilding the policies. A Dependency-Track policy is made of conditions, and each condition checks one subject, such as a licence or a severity. This table covers the fifteen subjects of Dependency-Track’s classic policies. Dependency-Track 5.0 also has expression-based policies, which this table doesn’t cover. Rewrite each of those by hand. Earnie policies are written in CEL (Common Expression Language), but Earnie and Dependency-Track describe components differently, so you can rarely copy an expression across unchanged. List the policies in your own Dependency-Track first, and note its version. Use this table to translate what you find, not to decide what you have. Earnie also has fields that Dependency-Track doesn’t, which you may want to use: Dual Licensed, Patent Clauses, License Data Source, Component Status, Match Percentage, the finding’s State and Domain, and the cryptography and AI provenance fields where your organisation has them. earnie policy show <policy-slug> prints the exact expression a policy runs.

Violation States and Exceptions

In Dependency-Track, each policy marks a violation as INFO, WARN, or FAIL. In Earnie, each policy has an action instead: Warn, Require approval, or Block. Start from what your pipeline does today. The SCANOSS GitHub Action failed on any Dependency-Track violation, whatever its state, so INFO, WARN, and FAIL all turned the check red. In that setup, every violation blocks. If your CI read Dependency-Track’s results directly instead, through its API or project badge, it could treat the states differently and block on FAIL only. Check which setup you’re replacing before you map anything. There’s no automatic translation. The action you choose decides how strict your gate is, so choose it with whoever owns your policies: Whichever you choose, write down the mapping and why you chose it. Your build behaves differently either way, and you’ll want the reason the first time a check turns green unexpectedly. A Policy Approval records:
  • a justification category, based on the CISA VEX justifications for why a risk doesn’t apply
  • a written reason
  • who approved it
  • an optional expiry date
  • any later revocation
Requesting an approval doesn’t change the result. Only an Admin’s decision does, and each approval covers one finding. See Request an approval. Every scan also records the exact version of each policy that judged it, so months later you can still see why a check failed.

What Changes for Your Team

  • One check, not three. Branch protection waits for Earnie instead of the three Policy Check: * checks.
  • Every decision has a name, a time, and a reason. A scanoss.json entry recorded none of those. Earnie records all three for every triage decision and Policy Approval. See Audit log. earnie scan audit <scan-id> prints the history of one scan: when it started, its gate, approvals that changed it, and what Earnie posted to the pull request.
  • You make decisions in Earnie, not in files. Instead of editing scanoss.json and pushing, you decide the finding or request an approval in Earnie, and the pull request updates without a push. Changing the code itself still needs a push, so Earnie can scan the change.
  • No local results file. Earnie doesn’t write .scanoss/results.json. The hook prints a short summary and a link, and the full results are in Earnie. Remove .scanoss/ from the repository and from .gitignore.
  • No upload to Dependency-Track. If other tools also send results to Dependency-Track and you want to keep using it, upload Earnie’s SBOM yourself. Run earnie export --bom-format cyclonedx --output sbom.json in a pipeline step, then upload the file in your own step. Earnie has nothing like Dependency-Track’s project versions: one Earnie project is one codebase for its whole life.
  • Scanning moves off developers’ machines. Instead of scanning locally with scanoss-py, the CLI sends your code to your Earnie environment, where it’s scanned and checked against your policies. By design, there’s no offline mode.
  • Fewer comments on each line. Earnie comments only on lines the pull request added, only for findings of Medium severity or higher, and at most ten times per review by default. Everything else goes in the summary comment. See Inline comments on the changed lines.
  • Posting results is separate from the result. If GitHub or GitLab refuses Earnie’s comment or check, the scan’s result still stands, and the scan’s page offers Retry publication. Retrying doesn’t run the scan again.
  • Results appear on the pull request and in Earnie only. Earnie doesn’t yet send policy notifications by email or chat. If you relied on Dependency-Track’s notifications, plan a replacement.

What’s Next

Start phase 1 with Workspace setup, then connect your repositories.