Fix GitLab CI License Compliance Check Failures (2026)

The core issue is that your GitLab CI pipeline is failing because the license compliance check, specifically the license_finder tool, can’t verify the licenses of your project’s dependencies. This is happening because license_finder is either not seeing your dependency lock files or it’s misinterpreting the license information within them.

Common Causes and Fixes:

1. Missing or Incorrectly Named Lock Files:

   • Diagnosis: license_finder relies on specific lock files generated by your package managers. For example, Gemfile.lock for Ruby, package-lock.json or npm-shrinkwrap.json for Node.js, Pipfile.lock for Python (Pipenv), poetry.lock for Python (Poetry), composer.lock for PHP, and go.sum for Go. Check if these files are present at the root of your repository or in the directory where your package manager commands are run.
   • Fix: Ensure the correct lock file for your primary language/package manager is committed to your repository and is accessible by the license_finder command in your CI job. If you’re using multiple package managers, commit all relevant lock files.
     • Example (Ruby): commit Gemfile.lock
     • Example (Node.js): commit package-lock.json
     • Example (Python Pipenv): commit Pipfile.lock
     • Example (Python Poetry): commit poetry.lock
     • Example (PHP Composer): commit composer.lock
     • Example (Go): commit go.sum
   • Why it works: license_finder parses these lock files to identify all direct and transitive dependencies and their versions. Without them, it has no definitive list of what’s installed.

2. license_finder Not Run in the Correct Directory:

   • Diagnosis: The CI job might be executing the license_finder command from a directory other than the one containing your lock files.
   • Fix: In your .gitlab-ci.yml, ensure you cd into the correct project directory before running license_finder. If your lock files are at the repository root, no cd is needed. If they are in a subdirectory (e.g., backend/), use cd backend/ before invoking license_finder.
     • Example:

       license_check:
         stage: test
         script:
           - cd backend/
           - bundle exec license_finder --format=json > license_report.json
           - echo "License report generated."
       

   • Why it works: license_finder looks for lock files relative to its current working directory.

3. Dependency Installation Step Missing or Incorrect:

   • Diagnosis: license_finder can sometimes operate by inspecting installed dependencies directly if lock files are unavailable or incomplete. If your CI job doesn’t install dependencies before running license_finder, it might not find anything to check.
   • Fix: Add or verify the dependency installation step in your CI job before license_finder runs.
     • Example (Ruby): bundle install
     • Example (Node.js): npm ci (preferred for CI) or npm install
     • Example (Python Pipenv): pipenv install --deploy --system
     • Example (Python Poetry): poetry install
     • Example (PHP Composer): composer install --no-dev
     • Example (Go): go mod tidy && go mod download
   • Why it works: This ensures that all necessary packages are present in the CI environment, allowing license_finder to inspect them if needed, or to confirm the lock file’s accuracy.

4. Unrecognized or Missing License Information in Dependencies:

   • Diagnosis: Some dependencies might not explicitly declare their license in their metadata (e.g., package.json, .gemspec, pyproject.toml). license_finder might flag these as "unknown" or "unapproved."
   • Fix:
     • Option A (Preferred): Update the problematic dependency to a version that correctly declares its license, or find an alternative package.
     • Option B (Configuration): Configure license_finder to explicitly allow or ignore specific dependencies or licenses. You can do this via a .license.yml file or command-line arguments.
       • Example (.license.yml to allow some-unlicensed-lib):

         ignore_paths:
           - "some_directory/"
         allowed_licenses:
           - MIT
           - Apache-2.0
         packages_root: vendor/ # if applicable
         dependencies_sources:
           - gem
           - npm
         # Allow specific package with unknown license
         # Note: This is a last resort and should be reviewed carefully.
         # It's better to fix the dependency or find an alternative.
         # For demonstration, let's say 'some-unlicensed-lib' is a specific dependency
         # you want to allow despite its license status.
         # license_finder doesn't have a direct 'allow_package' by name for unknown licenses,
         # but you can manage this via 'ignored_groups' or by setting a default license.
         # A more robust approach is often to add a custom license definition if possible,
         # or to use the 'add_to_unapproved' command line flag if you want license_finder
         # to *recognize* it but not fail.
         # The most direct way to *ignore* a specific dependency that has an unknown license
         # is often by using the configuration to define its license or ignore it.
         # For simplicity and common use cases, focus on 'allowed_licenses'.
         # If a package has NO license declared, license_finder will often report it as 'unknown'.
         # You can configure license_finder to *ignore* packages with unknown licenses:
         # ignore_unknown_licenses: true
         

       • Example (Command line to add an unknown license package):

         bundle exec license_finder --add-to-unapproved=some-unlicensed-lib
         

   • Why it works: Explicitly defining allowed licenses or instructing license_finder on how to handle packages with missing license metadata prevents the check from failing due to incomplete information.

5. Custom License Definitions or Scans:

   • Diagnosis: If your project uses internal or custom-licensed components, license_finder might not recognize them by default.
   • Fix: You can define custom licenses or scan directories for licenses using license_finder’s configuration or command-line options.
     • Example (.license.yml for custom license):

       custom_license_expressions:
         - name: MyInternalLicense
           expression: "(Internal-Proprietary AND NOT (GPL OR MIT))"
       

     • Example (Command line to add a custom license definition):

       bundle exec license_finder --custom-license 'MyInternalLicense=(Internal-Proprietary AND NOT (GPL OR MIT))'
       

   • Why it works: This allows license_finder to understand and evaluate licenses that aren’t part of its standard SPDX-based definitions.

6. license_finder Not Installed or Incorrect Version:

   • Diagnosis: The license_finder executable might not be installed in your CI environment, or an incompatible version is being used.
   • Fix: Ensure license_finder is installed as part of your CI job’s setup. If you’re managing it via a package manager (e.g., gem install license_finder), make sure that installation step is present and successful. If you’re using it via bundle exec, ensure it’s listed in your Gemfile.
     • Example (in Gemfile):

       gem 'license_finder', '~> 5.0' # Use a specific, known-good version
       

     • Example (in .gitlab-ci.yml script):

       before_script:
         - gem install license_finder -v 5.0.0 # Or run bundle install if using Gemfile
       

   • Why it works: The license_finder tool must be present and executable for the check to run. Specifying a version helps avoid unexpected behavior from updates.

The next error you’ll likely encounter after resolving license compliance issues is a failure in a subsequent testing or security scanning stage, as the pipeline progresses through its defined stages.