1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
|
---
stage: Govern
group: Compliance
info: "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"
type: reference, api
---
# External Status Checks API **(ULTIMATE)**
> - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3869) in GitLab 14.0, disabled behind the `:ff_external_status_checks` feature flag.
> - [Feature flag removed](https://gitlab.com/gitlab-org/gitlab/-/issues/320783) 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.
```plaintext
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 |
```json
[
{
"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](../administration/feature_flags.md) 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](../administration/feature_flags.md) named `status_checks_add_status_field`. Disabled by default.
> - `pass` status to pass checks is [deprecated](https://gitlab.com/gitlab-org/gitlab/-/issues/339039) in GitLab 14.9. Replaced with `passed`.
> - Support for `failed` and `passed` [enabled by default](https://gitlab.com/gitlab-org/gitlab/-/issues/353836) 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.
```plaintext
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:
```plaintext
GET /projects/:id/external_status_checks
```
**Parameters:**
| Attribute | Type | Required | Description |
|---------------------|---------|----------|---------------------|
| `id` | integer | yes | ID of a project |
```json
[
{
"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:
```plaintext
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:
```plaintext
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:
```plaintext
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](../user/project/merge_requests/status_checks.md).
|
