External status checks

An external status check sends a project’s merge requests to an outside service, which answers with a passed or failed status that can gate the merge. These actions manage a project’s checks (list, create, update, delete), list the status of each check on one merge request, set that status, and retry a check that failed.

Sample questions

• “Which external status checks does project 42 have?”
• “Show the status checks of merge request !15”
• “Retry the failed compliance check on merge request !15”

How to call it

• Dynamic, the default surface: call gitlab_execute_action with action set to the action’s ID, such as external_status_check.create_project, and its parameters in params. gitlab_find_action finds an ID from a description of the task.
• Meta (GITLAB_MCP_TOOL_SURFACE=meta): call gitlab_external_status_check with action set to the action’s name, such as create_project, and its parameters in params.
• Individual (GITLAB_MCP_TOOL_SURFACE=individual): call the action’s own tool, such as gitlab_create_project_external_status_check, with its parameters as the arguments.

Availability

How many of these actions an instance serves at each tier, out of a total of 8:

• Free: 0
• Premium: 0
• Ultimate: 8

Read-only actions: 3 of 8, the ones a deployment in read-only mode keeps. A token with read_api and not api is served 3 of the 8.

Actions

The description of each action, and of each of its parameters, is the text the server serves for it on the default surface, quoted as served. The token lines say what GitLab 19.4.1 requires of a token for the requests each action sends; on an instance with Admin Mode turned on, an action only an administrator may run also needs admin_mode. A destructive action runs only once confirmed, unless GITLAB_MCP_YOLO_MODE (or AUTOPILOT) skips that step: the dynamic surface needs confirm: true on gitlab_execute_action, and the other two take a confirm parameter or the client’s prompt (Destructive actions).

Action	Individual
external_status_check.create_project	gitlab_create_project_external_status_check
external_status_check.delete_project	gitlab_delete_project_external_status_check
external_status_check.list_project	gitlab_list_project_external_status_checks
external_status_check.list_project_checks	gitlab_list_project_status_checks
external_status_check.list_project_mr_checks	gitlab_list_project_mr_external_status_checks
external_status_check.retry_project	gitlab_retry_failed_external_status_check_for_project_mr
external_status_check.set_project_mr_status	gitlab_set_project_mr_external_status_check_status
external_status_check.update_project	gitlab_update_project_external_status_check

external_status_check.create_project

Create an external status check service for a project. Returns: the created check with id, name, external_url, hmac, and protected branches. See also: external_status_check.list_project, external_status_check.update_project, external_status_check.delete_project.

• Meta-tool: gitlab_external_status_check, action create_project
• Individual tool: gitlab_create_project_external_status_check
• Tier: Ultimate
• Classic or OAuth token: api
• Fine-grained token: External Status Check Service: Create at project (permissions page)
• Behavior: writes, not idempotent

Parameter	Type	Mandatory	Description
external_url	string	yes	External URL for the status check
name	string	yes	Name of the external status check
project_id	string/integer	yes	Project ID or URL-encoded path
protected_branch_ids	integer[]	no	IDs of protected branches to scope the check to
shared_secret	string	no	Shared secret for HMAC verification

external_status_check.delete_project

Delete a project external status check service permanently. Returns: a success confirmation. See also: external_status_check.list_project, external_status_check.create_project, external_status_check.update_project.

• Meta-tool: gitlab_external_status_check, action delete_project
• Individual tool: gitlab_delete_project_external_status_check
• Tier: Ultimate
• Classic or OAuth token: api
• Fine-grained token: External Status Check Service: Delete at project (permissions page)
• Behavior: writes, destructive (needs confirmation), idempotent

Parameter	Type	Mandatory	Description
check_id	integer	yes	External status check ID to delete
project_id	string/integer	yes	Project ID or URL-encoded path

external_status_check.list_project

List a project’s external status check services. Returns: each check with id, name, external_url, hmac, protected branches, and pagination metadata. See also: external_status_check.create_project, external_status_check.update_project, external_status_check.delete_project, external_status_check.list_project_mr_checks.

• Meta-tool: gitlab_external_status_check, action list_project
• Individual tool: gitlab_list_project_external_status_checks
• Tier: Ultimate
• Classic or OAuth token: read_api (or api)
• Fine-grained token: External Status Check Service: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column to order by for keyset pagination (e.g. id)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction: asc or desc

external_status_check.list_project_checks

List a project’s external status check services (deprecated endpoint). Returns: each check with id, name, external_url, hmac, protected branches, and pagination metadata. See also: external_status_check.list_project, external_status_check.create_project, external_status_check.list_project_mr_checks.

• Meta-tool: gitlab_external_status_check, action list_project_checks
• Individual tool: gitlab_list_project_status_checks
• Tier: Ultimate
• Classic or OAuth token: read_api (or api)
• Fine-grained token: External Status Check Service: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column to order by for keyset pagination (e.g. id)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction: asc or desc

external_status_check.list_project_mr_checks

List the external status checks for a merge request and their status. Returns: each check with id, name, external_url, status, and pagination metadata. See also: external_status_check.list_project, external_status_check.set_project_mr_status, external_status_check.retry_project.

• Meta-tool: gitlab_external_status_check, action list_project_mr_checks
• Individual tool: gitlab_list_project_mr_external_status_checks
• Tier: Ultimate
• Classic or OAuth token: read_api (or api)
• Fine-grained token: External Status Check: Read at project (permissions page)
• Behavior: read-only, idempotent

Parameter	Type	Mandatory	Description
merge_request_iid	integer	yes	Merge request internal ID
project_id	string/integer	yes	Project ID or URL-encoded path
order_by	string	no	Column to order by for keyset pagination (e.g. id)
page	integer	no	Page number to fetch, 1-based. Defaults to 1. Use the next_page field from the previous response to paginate forward.
page_token	string	no	Next page of a keyset listing: the next_page_token of the previous response of this action, passed back unchanged. It carries the position and every filter of the listing as GitLab read them, and those are what the next page is asked with, whatever filters are sent beside it. Leave it empty for the first page.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost, and a keyset page names the next one in next_page_token rather than next_page.
per_page	integer	no	Items per page. Defaults to 20, minimum 1, maximum 100. Use 100 to minimize round trips when the result set is large.
sort	string (asc, desc)	no	Sort direction: asc or desc

external_status_check.retry_project

Retry a failed external status check for a merge request. Returns: a success confirmation. See also: external_status_check.list_project_mr_checks, external_status_check.set_project_mr_status.

• Meta-tool: gitlab_external_status_check, action retry_project
• Individual tool: gitlab_retry_failed_external_status_check_for_project_mr
• Tier: Ultimate
• Classic or OAuth token: api
• Fine-grained token: External Status Check: Retry at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
check_id	integer	yes	External status check ID to retry
merge_request_iid	integer	yes	Merge request internal ID
project_id	string/integer	yes	Project ID or URL-encoded path

external_status_check.set_project_mr_status

Set the status of an external status check for a merge request. Returns: a success confirmation. See also: external_status_check.list_project_mr_checks, external_status_check.retry_project.

• Meta-tool: gitlab_external_status_check, action set_project_mr_status
• Individual tool: gitlab_set_project_mr_external_status_check_status
• Tier: Ultimate
• Classic or OAuth token: api
• Fine-grained token: External Status Check: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
external_status_check_id	integer	yes	External status check ID to update
merge_request_iid	integer	yes	Merge request internal ID
project_id	string/integer	yes	Project ID or URL-encoded path
sha	string	yes	Head SHA of the merge request source branch
status	string	yes	Status value (e.g. passed, failed)

external_status_check.update_project

Update a project external status check service. Returns: the updated check with id, name, external_url, hmac, and protected branches. See also: external_status_check.list_project, external_status_check.create_project, external_status_check.delete_project.

• Meta-tool: gitlab_external_status_check, action update_project
• Individual tool: gitlab_update_project_external_status_check
• Tier: Ultimate
• Classic or OAuth token: api
• Fine-grained token: External Status Check Service: Update at project (permissions page)
• Behavior: writes, idempotent

Parameter	Type	Mandatory	Description
check_id	integer	yes	External status check ID to update
project_id	string/integer	yes	Project ID or URL-encoded path
external_url	string	no	Updated external URL
name	string	no	Updated name
protected_branch_ids	integer[]	no	Updated protected branch IDs
shared_secret	string	no	Updated shared secret for HMAC verification