How GitHub maintains compliance for open source dependencies

Managing the open source license compliance process

Nearly all software carries some kind of license agreement. The license gives you permission to use a project, provided you comply with its obligations. Those obligations may be as simple as giving credit to the original author in your documentation, or they may require you to distribute all your source code when shipping your program. In some cases, licenses may also restrict certain activities or categories of use.

Your organization likely has its own policies about acceptable licenses based on your business model, software ecosystem, and distribution strategy. For example, suppose your organization sells a commercial, closed source binary application. You may want to prevent dependencies that would require you to open source your proprietary code. Or, you may have a project that you plan to release as an open source package. In this case, you may want to avoid including dependencies governed by commercial or incompatible open source licenses.

If you can’t comply with the obligations required in either scenario, you should avoid the dependency to prevent legal or operational risks. It may require engineering effort to remove these licenses after the fact. For enterprise software, the business risk of noncompliance is huge because it can lead to costly litigation and reputational damage.

Traditionally, license reviews have been performed manually or with third-party software. But now, GitHub has introduced a license compliance feature for GitHub Advanced Security customers, enabling you to review new dependencies directly on pull requests. This review helps ensure that the licenses for those dependencies comply with your policy, while also giving you the flexibility to expand your policy to allow new licenses or individual projects.

Two months ago, GitHub’s OSPO migrated from internal-only tools that we’d built to manage compliance onto the new feature. As early adopters, we gave the development team quick feedback and helped ensure the feature would clear the bar for large, fast-moving enterprises with complex compliance requirements.

Setting up for policy success

Because GitHub had built internal license compliance tools prior to the introduction of the product, we had an existing list of acceptable licenses to use as our initial policy. You’ll likely find that many dependencies use common permissive licenses such as MIT, Apache 2.0, and BSD-3-Clause, which are a good starting list to seed your policy.

We initially rolled the feature out using the “Evaluate” mode on an organization-wide ruleset, which generated annotations in pull requests without blocking merges, so we were able to get developers accustomed to the new workflow without impeding their productivity. Running the old and new tools in parallel also let us see if their behavior diverged. After about a month of this mode of operation, we got to a state where the alerts were mainly on packages with unusual, missing, or explicitly disallowed licenses.

How GitHub license compliance works

Under the hood, license compliance checks are enabled via rulesets. We target repositories via a custom property, where the value of the property determines whether license checks are enabled in “Active” or “Evaluate” mode.

In repositories that are targeted by a ruleset, pull requests that modify a project’s dependencies trigger a scan that looks up the licenses used by each of the new dependencies. If the new dependencies’ licenses are already permitted, or there are package-specific exceptions, the checks pass. If there are failures, either in the direct or transitive dependencies, the tool comments on the pull request with alerts for each problematic package.

The developer then reviews the alerts. If they decide the dependency is unacceptable, they can update their code or close the pull request to remove it. If they believe the license or package should be allowed, they can raise an exception request which will notify a specific team in the organization who can decide whether and how to amend the policy.

A day in the life of the license policy team

GitHub’s license policy team consists of OSPO members and engineers with expertise in license reviews and supply chain analysis. Since we are a worldwide company, our policy review team has members across time zones to review alerts in a timely manner. We are in the process of formalizing an SLA for reviewing license requests, but in practice it’s rarely more than a couple of hours before we can triage an incoming request.

Team members receive email notifications of new review requests and can also access a dashboard to see the backlog of pending requests.

When approving a request, we have two decision points:

• First, whether to permit the license or the package.
• Then, decide what scope – enterprise or repository – to use.

If it’s a safe license that simply hasn’t shown up before, we’ll add it at the enterprise level and thus allow dependencies with that license anywhere at GitHub. Some packages carry a commercial license which can’t be permitted everywhere but should be allowed in the repository owned by a team which has paid for the software, so those policy amendments get added at the repository level.

Package exceptions are useful for internal software which usually doesn’t have license data associated with it. Helpfully, the tool supports wildcard matches for package exceptions. For example, we’ve permitted everything in the @github-ui/* React namespace, so we don’t need to approve those packages one by one.

Making it easy for developers

To support this process, we’ve established procedures about contacting the GitHub OSPO, and how to use an emergency “break glass” override. These situations should be rare, but a clear emergency override process is essential for critically time-sensitive pull requests.

As we mentioned above, the license policy enforcement happens via ruleset, and the ruleset condition keys off a custom property. So toggling the value of the property can temporarily turn off enforcement if there’s a critical fix that’s blocked by a license alert. So far, we’ve only needed to use this once, but it was very helpful to have the option.

We’ve also provided internal documentation and training to help developers understand the importance of license compliance. Ultimately, it’s everyone’s job to help ensure compliance and manage risk and it’s our job to make that as easy as possible.

Wrapping up

License compliance is a critical part of managing our software supply chain. By helping developers make informed dependency choices aligned with GitHub’s license policy we prevent costly rewrites and potential legal problems.

We’ve been enthusiastically using and providing feedback on the new GitHub License Compliance feature for several months. Now that it’s in public preview, we are excited to see more companies adopt it and hope our experience provides some guidance if you’re just getting started.

GitHub Enterprise Cloud customers can use the License Compliance feature across repositories which have an active GHAS Code Security license. For more information, see About open source license compliance.

Jeff helps run GitHub’s Open Source Programs Office, focused on open source license compliance and software supply chain integrity. Before GitHub, he was Director of Open Source at PEAK6 and founder/CTO of Palamida, one of the first software composition analysis companies. Since 2004, Jeff has helped hundreds of software organizations use open source effectively while meeting license obligations.

Eric is a product manager at GitHub, focused on supply chain security. He's been working on open source at scale for a couple of decades, first as an SRE and more recently as a PM. For a thrilling conversation, ask him about Software Bill of Materials data formats, SPDX license expressions, or transitive package dependencies! Outside of tech, Eric does live audio and lighting for heavy metal concerts and enjoys getting muddy on his gravel bike.