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.

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. 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
• 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
• 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
• 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	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
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
• 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	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
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
• 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	Keyset pagination cursor: record id at which to fetch the next page, taken from the previous keyset response. Only used when pagination=‘keyset’.
pagination	string	no	Pagination method: ‘keyset’ for keyset-based pagination on large ordered result sets, or ‘offset’ (the default). Keyset avoids deep-offset cost.
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
• 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
• 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
• 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