• Block merges of merge requests unless all status checks have passed
• Lifecycle
• View the status checks on a project
• Add or update a status check service
  • Add a status check service
  • Update a status check service
  • Form values
    • Service name
    • API to check
    • Target branch
• Delete a status check service
• Status checks widget
• Troubleshooting
  • Duplicate value errors
  • Invalid URL error
  • Branch list error during retrieval or search
  • Failed to load status checks
• Related topics

External status checks

Status checks are API calls to external systems that request the status of an external requirement.

You can create a status check that sends merge request data to third-party tools. When users create, change, or close merge requests, GitLab sends a notification. The users or automated workflows can then update the status of merge requests from outside of GitLab.

With this integration, you can integrate with third-party workflow tools, like ServiceNow, or the custom tool of your choice. The third-party tool respond with an associated status. This status is then displayed as a non-blocking widget within the merge request to surface this status to the merge request author or reviewers at the merge request level itself.

You can configure merge request status checks for each individual project. These are not shared between projects.

For more information about use cases, feature discovery, and development timelines, see epic 3869.

Block merges of merge requests unless all status checks have passed

By default, merge requests in projects can be merged even if external status checks fail. To block the merging of merge requests when external checks fail:

1. On the left sidebar, select Search or go to and find your project.
2. Select Settings > Merge requests.
3. Select the Status checks must succeed checkbox.
4. Select Save changes.

Lifecycle

External status checks have an asynchronous workflow. Merge requests emit a merge request webhook payload to an external service whenever:

• The merge request is changed. For example, title or description.
• Code is pushed to the source branch of the merge request.
• A comment is made in the merge request discussion.

When the payload is received, the external service can then run any required processes before posting its response back to the merge request using the REST API.

Merge requests return a 409 Conflict error to any responses that do not refer to the current HEAD of the source branch. As a result, it’s safe for the external service to process and respond to out-of-date commits.

External status checks have the following states:

• pending - The default state. No response has been received by the merge request from the external service.
• passed - A response from the external service has been received and approved by it.
• failed - A response from the external service has been received and denied by it.

If something changes outside of GitLab, you can set the status of an external status check using the API. You don’t need to wait for a merge request webhook payload to be sent first.

View the status checks on a project

Within each project’s settings, you can see a list of status check services added to the project:

1. In your project, go to Settings > Merge requests section.
2. Scroll down to Status checks.

This list shows the service name, API URL, and targeted branch. It also provides actions to allow you to create, edit, or remove status checks.

Add or update a status check service

Add a status check service

Within the Status checks sub-section, select the Add status check button. The Add status check form is then shown.

Filling in the form and selecting the Add status check button creates a new status check.

Update a status check service

Within the Status checks sub-section, select the Edit button next to the status check you want to edit. The Update status check form is then shown.

Changing the values in the form and selecting the Update status check button updates the status check.

Form values

For common form errors see the troubleshooting section below.

Service name

This name can be any alphanumerical value and must be set. The name must be unique for the project. The name has to be unique for the project.

API to check

This field requires a URL and must use either the HTTP or HTTPs protocols. We recommend using HTTPs to protect your merge request data in transit. The URL must be set and must be unique for the project.

Target branch

If you want to restrict the status check to a single branch, you can use this field to set this limit.

The branches list is populated from the projects protected branches.

You can scroll through the list of branches or use the search box when there are a lot of branches and the branch you are looking for doesn’t appear immediately. The search box requires three alphanumeric characters to be entered for the search to begin.

If you want the status check to be applied to all merge requests, you can select the All branches option.

Delete a status check service

Within the Status checks sub-section, select the Remove… button next to the status check you want to delete. The Remove status check? modal is then shown.

To complete the deletion of the status check you must select the Remove status check button. This permanently deletes the status check and it is not recoverable.

Status checks widget

The status checks widget displays in merge requests and displays the following statuses:

• pending (), while GitLab waits for a response from an external status check.
• success () or failed (), when GitLab receives a response from an external status check.

When there are pending status checks, the widget polls for updates every few seconds until it receives a success or failed response.

To retry a failed status check:

1. Expand the merge request widget to show the list of external status checks.
2. Select Retry () on the failed external status check row. The status check is put back into a pending state.

An organization might have a policy that does not allow merging merge requests if external status checks do not pass. However, the details in the widget are for informational purposes only. GitLab does not prevent merging of merge requests that fail status checks. Support to allow merges to be blocked when external status checks fail is proposed in epic &8516.

Troubleshooting

Duplicate value errors

Name is already taken
---
External API is already in use by another status check

On a per project basis, status checks can only use a name or API URL once. These errors mean that either the status checks name or API URL have already been used in this projects status checks.

You must either choose a different value on the current status check or update the value on the existing status check.

Invalid URL error

Please provide a valid URL

The API to check field requires the URL provided to use either the HTTP or HTTPs protocols. You must update the value of the field to meet this requirement.

Branch list error during retrieval or search

Unable to fetch branches list, please close the form and try again

An unexpected response was received from the branches retrieval API. As suggested, you should close the form and reopen again or refresh the page. This error should be temporary, although if it persists, check the GitLab status page to see if there is a wider outage.

Failed to load status checks

Failed to load status checks

An unexpected response was received from the external status checks API. You should:

• Refresh the page in case this error is temporary.
• Check the GitLab status page if the problem persists, to see if there is a wider outage.

Related topics

• External status checks API