Discovery II: Create API-based approval rules for merge request compliance checks

Problem to solve

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 for our discovery on this feature.

Intended users

User experience goal

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

Within a Project's settings for Merge Request Approval Rules

  • Project maintainer creates a new project-level "API Approval" approval rule (as the designs 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
Screen_Shot_2020-08-25_at_12.47.35 Approvers__0_ Approvers__1__-_Default Approval_gate Approval_gate__with_data_ Project_level_approval_rule__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 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
image Merge_Request__Preview_ Merge_Request__Expand_-Failure Merge_Request__Expand_-Hover
workflowsolution validation

Riskiest Assumptions

backend (discussed here)

  • Customers have infrastructure that permits external services, like GitLab, to send data payloads to their network
  • Customers have infrastructure that permits communicating with external services, like GitLab, to make API-based decisions like this

UX

  • Project Maintainers/Owners will easily discover how to add an Approval service API to their Merge Request
  • Merge Request participants will understand how Approval gate checks informs the Merge Request.
  • 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

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 to the group-level to assist compliance-minded organizations with the enforcement of this type of rule.

Permissions and Security

Documentation

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

What does success look like, and how can we measure that?

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

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)

What is the type of buyer?

Skyler (Chief Information Security Officer)

Therefore, this should be an GitLab Ultimate feature.

Is this a cross-stage feature?

Yes. This likely involves groupsource code

Links / references

Milestone Goals

Edited by Austin Regnery