Configuring open source license policies

Create and enforce open source license policies to control which licenses your dependencies are allowed to use.

Who can use this feature?

Organizations owned by a GitHub Enterprise account with GitHub Code Security enabled

In this article

Prerequisites

Before you configure license policies, ensure that:

  • You are using GitHub Enterprise Cloud (including data-resident GHEC), and your organization has GitHub Code Security enabled on the repositories you want to use license compliance.
  • You have access to manage enterprise policy and rulesets.
  • Dependency graph is enabled for repositories you want to evaluate.

About license compliance

Open source license compliance lets you define a policy that specifies which licenses your dependencies are allowed to use.

When the policy is enforced with rulesets, GitHub evaluates pull requests that change package manifests, checks direct and transitive dependencies, and compares detected licenses to your policy. Pull requests with noncompliant dependencies remain blocked until violations are resolved.

Violations are typically resolved by:

  • Updating the pull request to use compliant dependencies
  • Approving an exception for a package
  • Updating policy to allow a license where appropriate

Configuring license compliance

Create a license policy

  1. Navigate to your enterprise. For example, from the Enterprises page on GitHub.com.
  2. At the top of the page, click Policies.
  3. In the sidebar, click License compliance.
  4. Click Default policy.
  5. On the Edit license policy page, click Add licenses and choose Select from list.
  6. From the license picker, select the licenses you want to permit. The licenses in this list are categorized based on their general risk level for use in corporate environments, but this is purely informational and does not constitute legal advice. Always check with your organization's legal team for policy guidance.
  7. Save your changes.

Alternately, if you have an existing license policy from another tool, you can import it as a list of SPDX expressions.

  1. On the Edit license policy page, click Add licenses and choose Manual input.
  2. Enter one or more SPDX license identifiers, each on a new line.
  3. Save your changes.

The licenses you add form your baseline policy. You can later add package-level exceptions when handling alerts.

Configure access for Enterprise Open-Source License Managers

  1. Navigate to your enterprise. For example, from the Enterprises page on GitHub.com.
  2. At the top of the page, click People.
  3. In the left sidebar, click Enterprise roles.
  4. Click Role assignments.
  5. Click Assign role.
  6. Select the Enterprise Open-Source License Manager role.
  7. Choose a user or team to assign the role to.
  8. Click Assign role.

Assigning this role also subscribes reviewers to request notifications so they can respond to dismissal requests quickly.

Optionally use custom properties to control rollout per repository

If you want a gradual rollout, use a repository custom property to control whether each repository is in inactive, evaluate, or active enforcement mode.

  1. On GitHub, navigate to the main page of the organization.

  2. Under your organization name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of the tabs in an organization's profile. The "Settings" tab is outlined in dark orange.

  3. In the sidebar, under "Code, planning, and automation", click Repository, then click Custom properties.

    Screenshot of an organization's settings page. In the sidebar, a link labeled "Custom properties" is outlined in orange.

  4. Create a single-select repository custom property, for example open_source_license_compliance.

  5. Add values for inactive, evaluate, and active.

  6. Set the default value to inactive.

  7. Decide who can change the property value.

  8. Assign property values to repositories based on their rollout stage.

Enforce policy in pull requests with rulesets

We suggest making two rulesets, one for Evaluate mode and one for Active mode. If you created custom properties to control the rollout, you can target those properties here.

  1. Go to the rulesets page for the scope where you want enforcement.

  2. Create a branch ruleset.

  3. Under the ruleset name, set Enforcement status:

    • For your first ruleset, select Evaluate.
    • For your second ruleset, select Active.

  4. Choose how to target repositories:

    • If you use custom properties, target by open_source_license_compliance:
      • For the evaluate-mode ruleset, target repositories where the property value is evaluate.
      • For the active-mode ruleset, target repositories where the property value is active.
    • If you do not use custom properties, target repositories by repository pattern or explicit repository selection.

  5. Enable Require license compliance results before merging.

  6. Save your changes.

For more information about rulesets, see About rulesets and Creating rulesets for repositories in your organization.

Test policy enforcement

  1. In a targeted repository, open a pull request that changes dependency manifests.
  2. Confirm that pull request annotations show license compliance results.
  3. If a dependency violates policy, review the generated alert and request dismissal if an exception is needed.

If the ruleset is in Active mode, the pull request remains blocked until all license policy violations are resolved.

Managing license compliance requests and policy

Review and handle exception requests

  1. As an Enterprise Open Source License Manager, open the list of pending license alert requests in your enterprise security views.
  2. Review each request and decide whether to deny or approve it.
  3. If you approve, choose whether the exception should apply to a package, a license, or a package pattern.
  4. Choose whether to apply the exception at repository scope or enterprise scope.
  5. Save the exception.

After a request is approved, the alert is closed and the pull request is unblocked, as long as no other required checks are failing.

Review effective policy for a repository

  1. On GitHub, navigate to the main page of the repository.

  2. Under your repository name, click Settings. If you cannot see the "Settings" tab, select the dropdown menu, then click Settings.

    Screenshot of a repository header showing the tabs. The "Settings" tab is highlighted by a dark orange outline.

  3. In the sidebar, under "Security", click License policy.

  4. Review the combined policy and exception set in effect for that repository.

  5. Update enterprise-level or repository-level policy as needed.

Package and license entries that are set at the enterprise level will not be editable in the repository policy. Items marked with a indicate repository-level entries which can be deleted.

Audit events

Changes to the license policy emit events to the audit log. These events are useful to review the history of changes or to feed external systems for compliance purposes. The log events are categorized as Policy Management, with a prefix of license_compliance_policy. They will have an action type create or modify. For details about the contents of the audit log events, see Audit log events for your organization.

License compliance API

There are several REST API endpoints for managing license compliance policy. You can use the API to programatically back up and restore your enterprise policy and to query whether a list of packages would create any policy violations if they were included in a repository's dependencies. In addition, operations on license compliance closure requests can generate webhook events when a request is created, receives a response, or is cancelled.

For details about the enterprise policy management API, see REST API endpoints for the dependency graph. For more about the package check API, see REST API endpoints for repositories. For more about webhooks, see Webhook events and payloads.

Further reading