gitlab-org--gitlab-foss/doc/api/status_checks.md

stage	group	info	type
Manage	Compliance	To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments	reference, api

External Status Checks API (ULTIMATE)

• Introduced in GitLab 14.0, disabled behind the :ff_external_status_checks feature flag.
• Feature flag removed in GitLab 14.1.

List status checks for a merge request

For a single merge request, list the external status checks that apply to it and their status.

GET /projects/:id/merge_requests/:merge_request_iid/status_checks

Parameters:

Attribute	Type	Required	Description
id	integer	yes	ID of a project
merge_request_iid	integer	yes	IID of a merge request

[
    {
        "id": 2,
        "name": "Rule 1",
        "external_url": "https://gitlab.com/test-endpoint",
        "status": "passed"
    },
    {
        "id": 1,
        "name": "Rule 2",
        "external_url": "https://gitlab.com/test-endpoint-2",
        "status": "pending"
    }
]

Set status of an external status check

• Introduced in GitLab 14.9, passed status to pass external status checks. Introduced with a flag named status_checks_add_status_field. Disabled by default.
• Introduced in GitLab 14.9, failed status to fail external status checks. Introduced with a flag named status_checks_add_status_field. Disabled by default.
• pass status to pass checks is deprecated in GitLab 14.9. Replaced with passed.

FLAG: On self-managed GitLab, by default setting passed instead of pass is unavailable. Also, setting failed is unavailable by default. To support setting passed and failed instead of only pass, ask an administrator to enable the feature flag named status_checks_add_status_field. On GitLab.com, this feature is not available.

For a single merge request, use the API to inform GitLab that a merge request has passed a check by an external service. To set the status of an external check, the personal access token used must belong to a user with at least the Developer role on the target project of the merge request.

Execute this API call as any user with rights to approve the merge request itself.

POST /projects/:id/merge_requests/:merge_request_iid/status_check_responses

Parameters:

Attribute	Type	Required	Description
id	integer	yes	ID of a project
merge_request_iid	integer	yes	IID of a merge request
sha	string	yes	SHA at HEAD of the source branch
external_status_check_id	integer	yes	ID of an external status check
status	string	no	Set to passed to pass the check or failed to fail it (GitLab 14.9 and later with feature flag status_checks_add_status_field enabled)
status	string	no	Set to pass to pass the check (GitLab 14.0 to GitLab 14.8, and GitLab 14.9 and later with feature flag status_checks_add_status_field disabled)

NOTE: sha must be the SHA at the HEAD of the merge request's source branch.

Get project external status checks

You can request information about a project's external status checks using the following endpoint:

GET /projects/:id/external_status_checks

Parameters:

Attribute	Type	Required	Description
id	integer	yes	ID of a project

[
  {
    "id": 1,
    "name": "Compliance Check",
    "project_id": 6,
    "external_url": "https://gitlab.com/example/test.json",
    "protected_branches": [
      {
        "id": 14,
        "project_id": 6,
        "name": "master",
        "created_at": "2020-10-12T14:04:50.787Z",
        "updated_at": "2020-10-12T14:04:50.787Z",
        "code_owner_approval_required": false
      }
    ]
  }
]

Create external status check

You can create a new external status check for a project using the following endpoint:

POST /projects/:id/external_status_checks

WARNING: External status checks send information about all applicable merge requests to the defined external service. This includes confidential merge requests.

Attribute	Type	Required	Description
id	integer	yes	ID of a project
name	string	yes	Display name of status check
external_url	string	yes	URL of status check resource
protected_branch_ids	array<Integer>	no	IDs of protected branches to scope the rule by

Delete external status check

You can delete an external status check for a project using the following endpoint:

DELETE /projects/:id/external_status_checks/:check_id

Attribute	Type	Required	Description
rule_id	integer	yes	ID of an status check
id	integer	yes	ID of a project

Update external status check

You can update an existing external status check for a project using the following endpoint:

PUT /projects/:id/external_status_checks/:check_id

Attribute	Type	Required	Description
id	integer	yes	ID of a project
rule_id	integer	yes	ID of an external status check
name	string	no	Display name of status check
external_url	string	no	URL of external status check resource
protected_branch_ids	array<Integer>	no	IDs of protected branches to scope the rule by

Related topics

• External status checks.