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 namedstatus_checks_add_status_field
. Disabled by default.- Introduced in GitLab 14.9,
failed
status to fail external status checks. Introduced with a flag namedstatus_checks_add_status_field
. Disabled by default.pass
status to pass checks is deprecated in GitLab 14.9. Replaced withpassed
.- Support for
failed
andpassed
enabled by default in GitLab 15.0 and feature flag removed.
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 |
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 |