Objective

This blog post demonstrates how to enforce acceptance criteria in GitLab merge requests using PowerShell pipelines. By validating that all checkboxes in linked issues are completed before a merge is allowed, development teams can ensure higher quality and consistency in their codebase. The solution leverages GitLab’s API to automatically check issue descriptions, report any unchecked items, and post comments on the merge request. This approach helps maintain accountability, reduces errors, and streamlines the review process for collaborative software projects.

Prerequisites

• Gitlab Account

Resolution

Gitlab

Create an Access Token

First, we need to go to Personal access tokens to create a new PAT in Gitlab. Click the “Add new token” button. Give your token a name, description (optional) and expiration date. In the Scope section, select api. You can review the scope permissions here.

Next, when it shows you your token, copy it down for later.

Add CI/CD Variable

Next, I am going to have this same pipeline with all of my projects, so I want the variable to be scoped agains the entire group. In Gitlab if I go to the group and then Settings > CI/CD I see a variables section.

Click the “Add variable” button in the right hand corner.

The Key for the variable should be “GITLAB_TOKEN” and the value is the access token from the previous step. You can change the key to something else but make sure you update the pipeline script to reference the new variable name. When finished, click ”Add Variable”.

Note: Make sure you check “Expand variable reference”

Add Repository Files

Next, we add the PowerShell script that the pipeline will execute, along with the GitLab CI/CD YAML file that defines the pipeline stages, job rules, and steps for validating that all checkboxes in linked issues are completed before a merge request can be merged. In this example, I will use a project named “Dev Test”.

I am starting with a blank repository, as shown below; however, you can also use an existing project that is not empty.

Add .ci Folder and Test-IssueCheckboxes.ps1

The first thing I am going to do is to create a folder called .ci that will contain my PowerShell script. This file is named, Test-IssueCheckboxes.ps1. You can name the file something else as well as place it in a different folder but you must modify your GitLab CI/CD YAML to point to the correct file name and location if you do. For the script contents, copy it from GitHub here.
The script has the following functions:

1. Get-EnvironmentVariable
2. Invoke-GitlabAPI
3. Get-MergeRequestDetails
4. Get-IssueDetails
5. Add-MergeRequestComment
6. Get-IssueReferences
7. Test-Checkboxes

You may also notice that there are several environment variables that we did not set such as CI_SERVER_URL, CI_PROJECT_ID, and CI_MERGE_REQUEST_IID. Gitlab automatically injects these predefined variables into every pipeline job.

Add .gitlab-ci.yml

Next, we need to add the yaml file to our repository that will run the pipeline stages and jobs. This file is named .gitlab-ci.yml and will be at the root of the repository. You can get the code for the file from GitHub here.

Now I have both my PowerShell script and my yaml file in the repository.

Configure Merge Requests

Next, we need to configure the repositories merge request policy to ensure that all pipelines must succeed in order for a merge request to be merged. In the repository go to Settings > Merge Requests and check the box “Pipelines must succeed”.

Testing it all

Making an Issue

First, I will make a new Gitlab issue that will have unchecked checkboxes.

Make a new branch and submit a MR

Next, I will make a new branch in my repository, make a change then submit a merge request. For this first test, I will not link the issue we created above anywhere. It will not be in the body or the title of the MR.

I can see the pipeline failed and a new comment has been added to my Merge Request stating that no item was linked to the MR by either the title or the description.

If I go back and link my issue to my merge request and re-run the job, it will produce a new error because there are several checkboxes that have not been marked complete.

If I go back to the issue, complete all the acceptance criteria and re-run the job, the pipeline will succeed and I can complete the merge request.