Breaking change exception: Remove support for License Compliance CI Template
Breaking Change Exception Request
Executive summary
The legacy License Compliance feature has been replaced with an SBOM-based license scanner, which provides significantly improved results for identifying licenses. We are seeking an exception to the breaking change policy in order to remove support for the existing license compliance analyzer in 16.3 for the following reasons:
- Maintaining both the existing license compliance features and the new SBOM-based license scanning approach will consume a lot of the team’s capacity. This greatly risks delaying important projects such as Continuous Vulnerability Scanning which is DevSecOps Adoption priority item #4.
- We have product functionality that will ensure this is of low-disruption for impacted customers - this involves using built-in error messaging AND group-level scan execution policies OR instance/group level CI variables.
- Compliance workflows in the product, such as License Approval Policies and Scan Execution Policies, will not be impacted by the removal of the existing License Compliance analyzer.
Impact assessment
How many customers are impacted?
Ultimate customers using the license compliance feature (.com and self-managed) upgrading to GitLab 16.3 will be impacted. Based on June and July 2023 data, this would impact around 1900 customers.
Additionally, the data used in the Dependency List view will change to not use the output of the License Scanning analyzer and instead will come from the SBOM output from Dependency Scanning. The licenses reported by these two detection methods vary from each other, though the differences may be noticeable.
Can we get the same outcome without a breaking-change?
No, because we cannot bulk migrate CI pipeline templates for customers. For additional context, please see this discussion.
Can the breaking-change wait till the next major release, or the next scheduled upgrade stop?
No, not without significant roadmap impact. If we have to wait to release this change, we will have to make a trade-off between maintaining the legacy license compliance feature or working on Continuous Vulnerability Scanning. The specific impacts are:
- Increase the likelihood of introducing new customer-impacting bugs in both features
- Increase MR review times significantly
- Reduce team velocity by 30% for 9 months
- Negatively impact teams that collaborate closely with Composition Analysis, such as Threat Insights, Security Policies, and Compliance
What is the alternative for customers to do the same job the change will break?
Alternative 1 - Use the newer SBOM-based license scanning feature + scan execution policies for groups
This option makes it quick and easy for customers to start using the new license scanning feature. This avoids having to update many projects manually.
Set up a scan execution policy at the group-level to enforce the SBOM-based license scan for all projects therein. Then, customers can update pipelines to remove the inclusion of the Jobs/License-Scanning.gitlab-ci.yml template in their CI configuration at their leisure.
While this is the lowest lift for customers, it may not work for all project configurations. There are some discrepancies in programming language support between the deprecated License Compliance analyzer and its replacement.
Alternative 2: Use the newer SBOM-based license scanning feature by including individually in CI pipelines for all impacted projects
Remove the old license compliance template from their CI pipeline and include the Dependency Scanning template for projects individually.
Alternative 3: Use the older license compliance feature
This is another option for customers to quickly re-enable license scanning for all projects by setting a CI variable at the group or instance level.
If users wish to continue using the older License Compliance feature, they can do so by setting the LICENSE_MANAGEMENT_VERSION CI variable to 4. This variable can be set at the project, group or instance level. This configuration change will allow customers to continue using an existing version of the License Compliance without having to adopt the new approach.
For customers who opt to pin the license management version via CI variables, it should be noted that this setting will follow the standard CI variable precedence.
How difficult is it for customers to migrate to the alternative? Is there a migration plan?
Migrating to the alternative approach involves updating customer CI configurations. Specifically, customers will need to include the Dependency Scanning vendored template as part of their pipelines. It is anticipated that many customers who use the existing License Compliance features already use Dependency Scanning as well, resulting in no action being required.
To migrate, customers follow one of the alternatives outlined above. Setting up a scan execution policy at the group-level is a low-effort action, as an example. We have built-in error messages that will be surfaced when a customer runs a pipeline where this jobs fails (REMINDER that this pipeline DOES NOT fail). The error messages direct the customer to documentation on how to enable license scanning via the new scanner.
What will the customer experience be when this change is released?
- This removal does not break any customer pipelines.
- Data shown on the Dependency List view will change, though the overall functionality remains the same.
- The License Compliance template remains available, so customers can continue to run the old job. If they do this, the license scan will not execute, an error message will be displayed, and an exit code returned to "mark" the job as failed, making it visible to users.
- The error message explains how to remediate the job failure (how to upgrade) and how to restore the old behavior (with a disclaimer that it is no longer supported, new vulnerabilities or bugs will not be addressed). It also includes a URL to our documentation so we quickly add any additional updates if needed.
- Customers will need to follow one of the alternatives above to continue using license scanning.
Communication plan
Following the previous process, we have already communicated the removal to customers.
If customers do not read the deprecation or removal announcement or the release notes, the error message and documentation will explain what to do. If customers fail to remove the LC template, we fail the old LC job (but not the pipeline) with this error message:
The License Compliance analyzer was deprecated in GitLab 15.9 and removed in GitLab 16.3. Bugs and vulnerabilities in this legacy analyzer will no longer be fixed, and this error message can be resolved by removing Jobs/License-Scanning.gitlab-ci.yml from your CI configuration. Detection of software dependency licenses is now enabled by including Dependency Scanning as part of your project’s CI configuration. However, the legacy License Compliance analyzer may still be used by updating the LICENSE_MANAGEMENT_VERSION variable to 4 in your CI configuration. Please see https://docs.gitlab.com/ee/user/compliance/license_compliance/ for more information.
Since the error message directs customers to the documentation page, we'll be able to quickly add updates if any additional troubleshooting tips are needed.
Tasks
-
Obtain approvals from the VP of Development, VP of Product Management, VP of Customer Support for this area (don't have one, so we are getting approvals from Directors of Customer Support), and CPO -
Group Manager of Secure - @sarahwaldner
-
Senior Engineering Manager, Secure - @twoodham -
VP of Engineering - @clefelhocz1 -
Senior Director of Product Management - @hbenson -
Customer Support - Since we do not have a VP of Customer Support we are asking for approval from the 4 directors -
Director of Customer Support - @lbot -
Director of Customer Support - @shaunmccann -
Director of Customer Support - @vparsons -
Director of Customer Support - @lyle - Lyle expressed support in Slack here. He is on PTO when we need this approved and we will therefore move forward with approval from the 3 other directors
-
-
Obtain approval from the CPO or CTO -
CPO - David Desanto
-
-
-
Notify Support and Customer Success so they can share information with relevant customers.