<!-- The first four sections: "Problem to solve", "Intended users", "User experience goal", and "Proposal", are strongly recommended, while the rest of the sections can be filled out during the problem validation or breakdown phase. However, keep in mind that providing complete and relevant information early helps our product team validate the problem and start working on a solution. --> ### Problem to solve <!-- What problem do we solve? Try to define the who/what/why of the opportunity as a user story. For example, "As a (who), I want (what), so I can (why/value)." --> Many compliance-minded organizations leverage external services when building, testing and deploying code. These external services perform various checks (e.g. code quality, security scanning, change control) that are detached from the GitLab merge request. Currently, there's no way to aggregate this external information and make these outputs a requirement for MR approvals. This creates a disjointed experience for MRs in complex compliance environments and requires additional work by our customers to stitch this data together. Please see [this issue](https://gitlab.com/gitlab-org/gitlab/-/issues/196115) for our discovery on this feature. ### Intended users * [Cameron (Compliance Manager)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#cameron-compliance-manager) * [Sidney (Systems Administrator)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sidney-systems-administrator) ### User experience goal <!-- What is the single user experience workflow this problem addresses? For example, "The user should be able to use the UI/API/.gitlab-ci.yml with GitLab to <perform a specific task>" https://about.gitlab.com/handbook/engineering/ux/ux-research-training/user-story-mapping/ --> A user can create an approval rule that accepts an API endpoint that they can use to incorporate external system output within their GitLab MRs. ### Proposal – this feature should be behind a ~"feature flag" <!-- How are we going to solve the problem? Try to include the user journey! https://about.gitlab.com/handbook/journeys/#user-journey --> Within a Project's settings for Merge Request Approval Rules - Project maintainer creates a new **project-level** "API Approval" approval rule (as the [designs](https://gitlab.com/gitlab-org/gitlab/-/issues/219567/designs/Add_Approval_Rule_Modal_Options.png) illustrate) * Creates new `ProjectApprovalRule`, with `rule_type` of `api_approval` * Popover when hovering over icon * Users or Groups is the default option when modal is launched * `Number of approvals required` has moved, and will display a message when 0 |Current UX|🆕 Users or Groups - Default option with 0 approvers|🆕 Users or Groups - Default option with >0 approvers|🆕 Approval gate|with link (no validation)|🆕 Rule inline with popover| |---|---|---|---|---|---| ||||||| Within a specific Merge Request - Webhook is fired for any number of reasons (MR updated, created, etc.) - External service **performs some proprietary approval process** - External service **[makes API call to approve](https://docs.gitlab.com/ee/api/merge_request_approvals.html#approve-merge-request)** MR, as if it were a user. We'll need to extend this API so that the external service can identify itself. - Additional container to display approval gates alongside the approvers - Upon failure it should not impact merging, its purely for awareness but show count of how many failed |Current|🆕 Preview Approval gates|🆕 Approval gates with failure|🆕 Approval gates with success| |---|---|---|---| ||||| <details> <summary>~"workflow::solution validation"</summary> ### Riskiest Assumptions ~backend (discussed [here](https://gitlab.com/gitlab-org/gitlab/-/issues/219567#note_402272066)) - [x] Customers have infrastructure that permits external services, like GitLab, to send data payloads to their network - [x] Customers have infrastructure that permits communicating with external services, like GitLab, to make API-based decisions like this ~UX - [x] Project Maintainers/Owners will easily discover how to add an Approval service API to their Merge Request - [x] Merge Request participants will understand how Approval gate checks informs the Merge Request. - [Test internally: seek feedback from Pedro/Marcel](https://gitlab.com/gitlab-org/gitlab/-/issues/219567#note_407649797) - [x] Customers will eventually want a human being to be a second, explicit approval for these approval gates - Gather feedback after releasing the MVC ### Further details <!-- Include use cases, benefits, goals, or any other details that will help us understand the problem better. --> The external service should be polled at the end of all other jobs so it's the last thing that runs for an MR. This would ensure that any and all changes are captured in the data payload sent to the external system for propper vetting. We will need to bring [default approval rules](https://gitlab.com/gitlab-org/gitlab/-/issues/1111) to the group-level to assist compliance-minded organizations with the enforcement of this type of rule. ### Permissions and Security <!-- What permissions are required to perform the described actions? Are they consistent with the existing permissions as documented for users, groups, and projects as appropriate? Is the proposed behavior consistent between the UI, API, and other access methods (e.g. email replies)?--> ### Documentation <!-- See the Feature Change Documentation Workflow https://docs.gitlab.com/ee/development/documentation/workflow.html#for-a-product-change * Add all known Documentation Requirements in this section. See https://docs.gitlab.com/ee/development/documentation/feature-change-workflow.html#documentation-requirements * If this feature requires changing permissions, update the permissions document. See https://docs.gitlab.com/ee/user/permissions.html --> We'll need to add documentation to include an example `JSON Object` for this MR payload so customers know what data to expect for parsing and processing. Documentation should also included the GitLab API endpoint to submit a response to (`200 OK` or `400 BAD REQUEST`) and the data expected with each query. ### Availability & Testing <!-- This section needs to be retained and filled in during the workflow planning breakdown phase of this feature proposal, if not earlier. What risks does this change pose to our availability? How might it affect the quality of the product? What additional test coverage or changes to tests will be needed? Will it require cross-browser testing? Please list the test areas (unit, integration and end-to-end) that needs to be added or updated to ensure that this feature will work as intended. Please use the list below as guidance. * Unit test changes * Integration test changes * End-to-end test change See the test engineering planning process and reach out to your counterpart Software Engineer in Test for assistance: https://about.gitlab.com/handbook/engineering/quality/test-engineering/#test-planning --> ### What does success look like, and how can we measure that? <!-- Define both the success metrics and acceptance criteria. Note that success metrics indicate the desired business outcomes, while acceptance criteria indicate when the solution is working correctly. If there is no way to measure success, link to an issue that will implement a way to measure this. --> **Success metrics:** * API-based approval rule usage: A higher number of API calls and MRs using this feature suggests we've solved a painful problem for customers wanting to integrate external systems in this way. * Customers have less expensive and more reliable experiences incorporating external systems into GitLab's MR experience * Fewer non-developer related CI jobs in the project's pipeline **Acceptance criteria:** * As a `compliance manager` I want to integrate my company's complex, proprietary compliance workflows into the GitLab MR so that I can see all of the change's evidence in a single location, easily incorporate external decisions, and enforce a specific workflow for regulated projects <hr> Success is defined by the insights we gain based on customer usage API-based approval rules. We assume that customers see the current implementation, which relies on webhooks, as expensive and unreliable. By providing an avenue (outside of the pipeline view) to use an external API endpoint to receive a payload from GitLab, we expect to retain customers requesting this capability without negatively impacting the workflow of Sasha ([Software Developer](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/#sasha-software-developer)) ## What is the type of buyer? <!-- What is the buyer persona for this feature? See https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/buyer-persona/ In which enterprise tier should this feature go? See https://about.gitlab.com/handbook/product/pricing/#four-tiers --> [Skyler (Chief Information Security Officer)](https://about.gitlab.com/handbook/marketing/product-marketing/roles-personas/buyer-persona/#skyler---the-chief-information-security-officer) Therefore, this should be an ~"GitLab Ultimate" feature. ### Is this a cross-stage feature? <!-- Communicate if this change will affect multiple Stage Groups or product areas. We recommend always start with the assumption that a feature request will have an impact into another Group. Loop in the most relevant PM and Product Designer from that Group to provide strategic support to help align the Group's broader plan and vision, as well as to avoid UX and technical debt. https://about.gitlab.com/handbook/product/#cross-stage-features --> Yes. This likely involves ~"group::source code" ### Links / references - :tv: [Step 1 – API Approval Rule setup (Walkthrough)](https://youtu.be/MzzTDqTykQo) - :tv: [Step 2 – Approval Gates in Merge Request (Walkthrough)](https://youtu.be/FBCITzrkfIc) - ✏️ [Figma](https://www.figma.com/file/wWTJwed5c4EtRF4oy7Es4f/and-3869-External-API-Approval-Rules-for-Compliance-Checks?node-id=75%3A5) ### Milestone Goals - [ ] `13.4` Complete ~"workflow::solution validation"