> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/security-testing-orchestration/3.0/troubleshooting-and-resources/sto-use-cases/stop-builds-based-on-scan-results/gitlab-triggers.md).

# GitLab triggers to block merge requests with vulnerabilities

You can create GitLab event triggers to support a variety of STO workflows and use cases. This topic describes how to do the following:

* Trigger an STO pipeline in response to a GitLab MR that targets a protected branch and/or updates specific files.
* Include a keyword in a review comment to trigger a new scan if a previous pipeline execution failed.

The following steps outline the basic workflow:

1. [Create a trigger](#create-the-harness-trigger) for your Harness pipeline.

   This should automatically register an outbound webhook in your Git repo.
2. [Set up the failure criteria](#set-up-the-failure-criteria) for your STO pipeline.
3. [Create a merge request](#test-the-outbound-webhook-and-trigger) to test the webhook and trigger.

   When you create a merge request, GitLab sends a request to the Harness webhook. If the STO pipeline fails, it sends back a `failed` response that blocks the merge request.

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

These workflows require the following:

* A [Harness connector](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-lab-connector-settings-reference.md) to your GitLab account.
* A Harness pipeline with a code-repository scan step such as Semgrep.
* The [Codebase](/continuous-integration/use-harness-ci/use-harness-ci/codebase-configuration/create-and-configure-a-codebase.md) in your pipeline should point to the Git repo that you want to scan.

### Create the Harness trigger <a href="#create-the-harness-trigger" id="create-the-harness-trigger"></a>

The following sections describe two triggers that can be very useful in the context of STO scanning:

* [Trigger on a changed file](#trigger-on-a-changed-file)
* [Trigger on a review comment](#trigger-on-a-merge-request-comment)

#### Trigger on a changed file <a href="#trigger-on-a-changed-file" id="trigger-on-a-changed-file"></a>

You can specify a trigger that says: If a merge request updates any of these files, run the pipeline and scan the repo.

This type of trigger supports use cases such as:

* If the merge request updates any file that matches the trigger filter, run a SAST scan and block the PR if the scan results meet the [failure criteria](#set-up-the-failure-criteria).
* If the merge request updates a specific file of interest, such as a `pom.xml` workspace file, run an SCA scan and block the PR if the scan results meet the [failure criteria](#set-up-the-failure-criteria).

**Trigger setup**

1. Go to your STO pipeline, select **Triggers**, and add a new trigger.
2. Set up the trigger as follows.

[**Configuration**](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md#configure-the-trigger)

1. [Connector](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-lab-connector-settings-reference.md) to your GitLab account
2. **Repository name**
3. [Event](/harness-ai/use-harness-platform/triggers/triggers-reference.md#event-and-actions) = **merge request**
4. [Actions](/harness-ai/use-harness-platform/triggers/triggers-reference.md#event-and-actions) to trigger the pipeline

[**Condition**](/harness-ai/use-harness-platform/triggers/triggers-reference.md#conditions-settings)

The following conditions are the most relevant to this workflow. You can add other conditions as needed. Triggers are complex filters in which all conditions are AND-ed together.

1. **Target Branch** This should match your [target baseline](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/set-up-baselines.md), such as `main`.
2. [Changed Files](/harness-ai/use-harness-platform/triggers/triggers-reference.md#branch-and-changed-files-conditions) The files that trigger the STO pipeline if they have updates in the PR. You can specify multiple files using the [operators](/harness-ai/use-harness-platform/triggers/triggers-reference.md#operators) **In**, **Not In**, and **Regex**.

Here's a simple example: trigger a build if a PR seeks to update a specific `pom.xml` in the `main` branch.

[**Pipeline input**](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md#set-pipeline-input)

The pipeline input should be configured correctly, with **Build Type** set to **Git Pull Request**.

**Test the trigger**

After you create the trigger, proceed to [Set up the failure criteria](#set-up-the-failure-criteria).

<details>

<summary>YAML trigger example</summary>

```yaml

trigger:
  name: gitlab-trigger-on-mr-changed-file
  identifier: gitlabtriggeronmrchangedfile
  enabled: true
  description: ""
  tags: {}
  orgIdentifier: default
  stagesToExecute: []
  projectIdentifier: sto_tutorials
  pipelineIdentifier: triggertestgitlab
  source:
    type: Webhook
    spec:
      type: Gitlab
      spec:
        type: MergeRequest
        spec:
          connectorRef: your_gitlab_connector_id
          autoAbortPreviousExecutions: false
          payloadConditions:
            - key: changedFiles
              operator: Equals
              value: README.rst
            - key: targetBranch
              operator: Equals
              value: main
          headerConditions: []
          repoName: dvpwa-gitlab-tutorial
          actions:
            - Open
            - Update
            - Reopen
  inputYaml: |
    pipeline:
      identifier: triggertestgitlab
      properties:
        ci:
          codebase:
            build:
              type: PR
              spec:
                number: <+trigger.prNumber>


```

</details>

#### Trigger on a merge-request comment <a href="#trigger-on-a-merge-request-comment" id="trigger-on-a-merge-request-comment"></a>

You can specify a trigger that says: If a reviewer includes a specific keyword in a pull-request review comment, run the pipeline and scan the repo.

This type of trigger is useful when a pipeline execution fails for reasons other than the [failure criteria](#set-up-the-failure-criteria) you specified for the pipeline. If the STO scan doesn't finish in the original execution, a reviewer can add a review comment with a keyword such as `RERUN_STO_PIPELINE`.

**Trigger setup**

1. Go to your STO pipeline, select **Triggers**, and add a new trigger.
2. Set up the trigger as follows.

[**Configuration**](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md#configure-the-trigger)

1. [Harness Connector](/harness-ai/use-harness-platform/connectors/code-repositories/ref-source-repo-provider/git-lab-connector-settings-reference.md) to your GitLab account
2. **Repository name**
3. [Event](/harness-ai/use-harness-platform/triggers/triggers-reference.md#event-and-actions) = **Merge Request**
4. [Actions](/harness-ai/use-harness-platform/triggers/triggers-reference.md#event-and-actions), such as **Open**, **Reopen**, and **Edit**, to trigger the scan. You can also select **All actions** to allow reviewers to trigger a scan at any time.

[**Condition**](/harness-ai/use-harness-platform/triggers/triggers-reference.md#conditions-settings)

The following conditions are the most relevant to this workflow. You can add other conditions as needed. Triggers are complex filters in which all conditions are AND-ed together.

1. **Target Branch** This should match your [target baseline](/security-testing-orchestration/troubleshooting-and-resources/sto-use-cases/set-up-sto-pipelines/set-up-baselines.md).
2. Enter the following [JEXL condition](/harness-ai/use-harness-platform/triggers/triggers-reference.md#jexl-conditions) with the keyword to trigger a new scan:

   `<+trigger.payload.object_attributes.description>.contains("RERUN_STO_SCAN")`

[**Pipeline input**](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md#set-pipeline-input)

The pipeline input should be configured correctly, with **Build Type** set to **Git Pull Request**.

**Test the trigger**

After you create the trigger, proceed to [Set up the failure criteria](#set-up-the-failure-criteria).

<details>

<summary>YAML trigger example</summary>

```yaml

trigger:
  name: trigger-on-mr-comment
  identifier: triggeronmrcomment
  enabled: true
  description: ""
  tags: {}
  orgIdentifier: default
  stagesToExecute: []
  projectIdentifier: sto_tutorials
  pipelineIdentifier: triggertestgitlab
  source:
    type: Webhook
    spec:
      type: Gitlab
      spec:
        type: MergeRequest
        spec:
          connectorRef: dbothwell1gitlab
          autoAbortPreviousExecutions: false
          payloadConditions:
            - key: targetBranch
              operator: Equals
              value: main
          headerConditions: []
          jexlCondition: "<+trigger.payload.object_attributes.description>.contains(\"RERUN_STO_SCAN\") "
          repoName: dvpwa-gitlab-tutorial
          actions:
            - Open
            - Reopen
            - Update
  inputYaml: |
    pipeline:
      identifier: triggertestgitlab
      properties:
        ci:
          codebase:
            build:
              type: branch
              spec:
                branch: <+trigger.branch>



```

</details>

### Set up the failure criteria <a href="#set-up-the-failure-criteria" id="set-up-the-failure-criteria"></a>

You can configure your Harness pipeline to fail if the scan finds vulnerabilities that match a specified set of criteria. You can use one of two methods:

* [Fail on Severity](/security-testing-orchestration/3.0/use-sto/sto-exempt-issues/exemption-workflows.md)

  Every STO scan step has a `fail_on_severity` setting that fails the step if a scan detects issues with the specified severity or higher. You can also create exemptions ("Ignore rules") for specific issues to override this behavior.
* [Governance policies](/security-testing-orchestration/3.0/use-sto/enforce-sto-policies-for-governance/create-opa-policies.md)

  You can use Harness Policy as Code to write and enforce policies against your security tests, and to block your pipelines if a security test has any issues that violate those policies. STO includes a set of predefined templates for blocking pipelines based on issue severity, reference ID, CVE age, title, and number of occurrences.

### Test the outbound webhook and trigger <a href="#test-the-outbound-webhook-and-trigger" id="test-the-outbound-webhook-and-trigger"></a>

#### Verify the webhook in GitLab <a href="#verify-the-webhook-in-gitlab" id="verify-the-webhook-in-gitlab"></a>

Once you add a trigger to your pipeline, your Git service provider should create a webhook for the trigger automatically. This is true for all non-custom webhooks and all Git providers supported by Harness.

1. Go to your GitLab account and select **Settings** > **Webhooks**.
2. If you don't see a webhook, you can add one manually. For more information, go to [Register the webhook in the Git provider](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md#register-the-webhook-in-the-git-provider).

#### Test the webhook and trigger <a href="#test-the-webhook-and-trigger" id="test-the-webhook-and-trigger"></a>

1. Create a merge request in your GitLab repo to verify that the trigger works as intended.
   * To verify the [changed-file trigger](#trigger-on-a-changed-file) described above:
     * Go to the root branch you specified in the trigger.
     * Update the file you specified in the trigger. Then create a merge request in a new branch.
   * To verify the [review-comment trigger](#trigger-on-a-merge-request-comment) described above, create a merge request and then add a review comment with the keyword you specified.
     * Go to the root branch you specified in the trigger.
     * Create a merge request in a new branch.
     * Add a review comment with the keyword you specified in the trigger.
2. Go to the GitLab pipeline for your merge request. The STO pipeline execution appears as an external check.

   When you create a merge request, GitLab creates an external status check and sends a payload to the Harness webhook. Then it waits for a response that indicates the pipeline status (`pending`, `passed`, or `failed`).

   For more information, go to [External status checks](https://docs.gitlab.com/ee/user/project/merge_requests/status_checks.html) in the GitLab documentation.
3. Go to the **Pipeline Executions** page of your Harness pipeline and verify that the trigger starts a new execution.
4. Go to the **Merge Request** page in GitLab and wait for the merge-request checks to finish.

   When the Harness pipeline finishes, it sends a response to GitLab that reports the execution status. If the response is `failed`, the external check fails and blocks the merge request.

If the trigger doesn't work as intended, go to [Troubleshoot Git event triggers](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md#troubleshoot-git-event-triggers).

#### Test the external status check <a href="#test-the-external-status-check" id="test-the-external-status-check"></a>

Now that you've set up the rule, trigger another Harness pipeline execution and fail it to verify that the rule stops the merge request.

{% hint style="info" %}
To verify the branch protection rule, you must ensure that your STO pipeline fails. To configure your pipeline to fail temporarily, you can do one of the following:

* Set [Fail on Severity](/security-testing-orchestration/3.0/new-to-sto/key-concepts/fail-pipelines-by-severity.md) to **Low** in the scan step of your pipeline. Then scan a repo with known vulnerabilities.
* Add a temporary Run step to your pipeline with the command `exit(1)`.
  {% endhint %}

1. Trigger another pipeline execution.
   * For the [changed-file trigger](#trigger-on-a-changed-file) described above, make and push a change. Then create a merge request.
   * For the [review-comment trigger](#trigger-on-a-merge-request-comment) described above, add a review comment with the keyword you specified.

Now, merging is blocked if the Harness pipeline fails.

### For more information <a href="#for-more-information" id="for-more-information"></a>

* The Harness platform docs include [extensive information about triggers](/harness-ai/use-harness-platform/triggers.md). The following topics are highly relevant to STO use cases:
  * [Trigger pipelines using Git events](/harness-ai/use-harness-platform/triggers/triggering-pipelines.md)
  * [Webhook triggers reference](/harness-ai/use-harness-platform/triggers/triggers-reference.md)
* For detailed information about outbound webhooks and branch protection rules, go to the docs for your source code management (SCM) provider. This topic describes a few simple GitLab workflows, but these topics are outside the scope of Harness documentation.