Quality Gates in Merge Requests
Quality gates are a quality control technique used in collaborative software development. Though it’s quite a broad term, Space currently uses it only for merge request workflows. Simply put, a quality gate is a set of conditions that needs to be met before you can merge your commit into a protected branch (for example, the master). Let’s take a look at them in more detail.
Types of quality gates
- Code review approvals, which must come from specified team members.
- Successfully completed Automation jobs.
- An external check, which passes if an external service approves the merge request by sending an HTTP API request to Space. For example, this could be an external CI/CD service.
Setting up quality gates for a repository
You can turn on quality gates for particular protected branches in the project repository.
- Open the project repository and go to Repositories.
- Select the required repository and open the Repository Settings.
- On the Protected Branches tab, either edit the existing rule or create a New rule. The rule pattern specifies which repositories should be treated as protected. By default, there’s already a rule for the master branch: +:refs/heads/master.
- In Push, specify who will be allowed to push commits that bypass merge requests. For example, you can remove all the users so that everyone will be required to create a merge request.
- Switch the Quality Gates for Merge Requests to On.
- In Members required to pass quality gates, specify who will be allowed to click the Merge button once all the quality gate conditions are satisfied.
Now, let’s set up the gates. In Requirements:
Approvals specify who must approve a code review. Here you should also specify how many approvals are enough. For example, if you specify two users and set the number to 1, just one approval from either of these users will be enough. If you set 2, then both will be required to approve the code review.
Jobs specify Automation jobs that must be successfully completed for a merge request to pass the quality gates. Note that in order to be on this list, a job must exist in the project’s .space.kts file and it must have been completed at least once.
- For simplicity, let’s skip the External checks option for now. We’ll return to it later in this post.
So, what does a typical merge workflow look like after you set up quality gates?
In the previous step, we set up the following repository restrictions:
Such a configuration:
- Prohibits pushing to the repo for everyone.
- Allows everyone with access to the repo to create merge requests and actually click the Merge button.
- Requires either Miles Dyson or Serena Kogan to approve a code review.
- Requires the Automation job "Build and run tests" to complete successfully.
A developer, let’s call her Sarah, creates a separate branch called sarah-changes and pushes her changes to that branch.
Sarah creates a merge request with Code Reviews | New merge request.
By default, ‘git push’ triggers the Automation job. Once the job is finished, this gate condition becomes satisfied:
The only required condition now is the approval from Miles. In theory, Serena’s approval could also allow the request to pass the gate but Sarah explicitly specified Miles as a reviewer.
When the merge request is created, Miles receives a notification in his chat. Now, by following the link in the chat message, he can check out the changes and approve them.
What does this look like to Sarah? The approval comes to the code review chat and the second quality gate becomes green. Now, she can click the Merge button.
That’s it! The change now is in the master branch after passing two quality gate conditions.
Setting up external checks as quality gates
So, what about external checks? In short, these make it possible to receive quality gate approval from an external service. The most obvious example is an external CI/CD server that sends an approval if the build finishes successfully.
What if you want your custom external service to be a provider of external checks? Here’s how to get started:
In Space, create an application of the Service Account type.
In Requested Rights, grant the application the Report external check status permission.
In Authorizations, add the desired project.
That’s basically all there is to it. Now, you should teach your service to send the Report External Check Status API request on behalf of the application you’ve just created. First, you can play with this request in the HTTP API Playground (as a revision number you can take any existing one).
After you make a request, the checks will be added to the repository settings:
That’s all that we wanted to tell you about quality gates today. Feel free to comment and ask questions and, of course, give them a try!