External status checks

Use this API to manage external status checks.

Get list of project external status checks

GET /api/v4/projects/{id}/external_status_checks

Parameters

Name	Type	Description
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesExternalStatusCheck
`400`	Bad Request	—
`404`	Not Found	—

Create external status check

POST /api/v4/projects/{id}/external_status_checks

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`branch_scope` Required	String	External status check branch scope Allowed values: `all_branches`, `all_protected_branches`, `protected_branch_specific` Minimum length: `1`
`external_url` Required	String	External status check resource url Example: `https://www.example.com`
`name` Required	String	External status check display name Example: `lorem ipsum`
`protected_branch_ids`	Array of integers	IDs of protected branches
`shared_secret`	String	HMAC shared secret Example: `hmac`
`timeout_minutes`	Integer	External status check timeout in minutes Example: `5`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesExternalStatusCheck
`400`	Bad Request	—
`404`	Not Found	—

Update external status check by id

PUT /api/v4/projects/{id}/external_status_checks/{check_id}

Parameters

Name	Type	Description
`check_id` Path, required	Integer	External status check ID Example: `1`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`branch_scope`	String	External status check branch scope Allowed values: `all_branches`, `all_protected_branches`, `protected_branch_specific`
`external_url`	String	External status check resource url Example: `https://www.example.com`
`name`	String	Display name of external status check Example: `lorem ipsum`
`protected_branch_ids`	Array of integers	IDs of protected branches to scope the rule by
`shared_secret`	String	HMAC shared secret Example: `hmac`
`timeout_minutes`	Integer	External status check timeout in minutes Example: `5`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesExternalStatusCheck
`400`	Bad Request	—
`404`	Not Found	—

Delete external status check

DELETE /api/v4/projects/{id}/external_status_checks/{check_id}

Parameters

Name	Type	Description
`check_id` Path, required	Integer	ID of an external status check
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

Set status of an external status check

POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/status_check_responses

Parameters

Name	Type	Description
`id` Path, required	String	ID of a project Example: `1`
`merge_request_iid` Path, required	Integer	IID of a merge request Example: `1`

Request body (application/json)

Property	Type	Description
`external_status_check_id` Required	Integer	ID of an external status check Example: `1`
`sha` Required	String	SHA at HEAD of the source branch Example: `5957a570eee0ac4580ec027fb874ad7514d1e576`
`status` Required	String	Set to `passed` to pass the check or `failed` to fail it Allowed values: `passed`, `failed` Minimum length: `1`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesMergeRequestsExternalStatusCheckResponse
`400`	Bad Request	—
`404`	Not Found	—

List status checks for a merge request

GET /api/v4/projects/{id}/merge_requests/{merge_request_iid}/status_checks

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`
`merge_request_iid` Path, required	Integer	The internal ID of an issuable

Responses

Code	Description	Schema
`200`	OK	APIEntitiesMergeRequestsExternalStatusCheck
`404`	Not Found	—

Retry failed external status check

POST /api/v4/projects/{id}/merge_requests/{merge_request_iid}/status_checks/{external_status_check_id}/retry

Parameters

Name	Type	Description
`id` Path, required	String	Project ID Example: `1`
`merge_request_iid` Path, required	Integer	Merge Request IID Example: `1`
`external_status_check_id` Path, required	Integer	Failed external status check ID

Responses

Code	Description	Schema
`202`	Accepted	—
`400`	Bad Request	—
`404`	Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesCiPipeline

Property	Type	Description
`archived`	Boolean	Example: `false`
`before_sha`	String	Example: `a91957a858320c0e17f3a0eca7cfacbff50ea29a`
`committed_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`coverage`	Number (float)	Example: `98.29`
`created_at`	String (date-time)	Example: `2015-12-24T15:51:21.880Z`
`detailed_status`	DetailedStatusEntity	—
`duration`	Integer	Time spent running in seconds Example: `127`
`finished_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`queued_duration`	Integer	Time spent enqueued in seconds Example: `63`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`started_at`	String (date-time)	Example: `2015-12-24T17:54:30.733Z`
`status`	String	Example: `success`
`tag`	Boolean	Example: `false`
`updated_at`	String (date-time)	Example: `2015-12-24T17:54:31.198Z`
`user`	APIEntitiesUserBasic	—
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`
`yaml_errors`	String	Example: `widgets:build: needs 'widgets:test'`

APIEntitiesCiPipelineBasic

Property	Type	Description
`created_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`id`	Integer (int64)	Example: `1`
`iid`	Integer	Example: `2`
`project_id`	Integer (int64)	Example: `3`
`ref`	String	Example: `feature-branch`
`sha`	String	Example: `0ec9e58fdfca6cdd6652c083c9edb53abc0bad52`
`source`	String	Example: `push`
`status`	String	Example: `success`
`updated_at`	String (date-time)	Example: `2022-10-21T16:49:48.000+02:00`
`web_url`	String	Example: `https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61`

APIEntitiesCustomAttribute

Property	Type	Description
`key`	String	Example: `foo`
`value`	String	Example: `bar`

APIEntitiesDiffRefs

Property	Type	Description
`base_sha`	String	Example: `b83d6e391c22777fca1ed3012fce84f633d7fed0`
`head_sha`	String	Example: `b83d6e391c22777fca1ed3012fce84f633d7fed0`
`start_sha`	String	Example: `b83d6e391c22777fca1ed3012fce84f633d7fed0`

APIEntitiesExternalStatusCheck

Property	Type	Description
`branch_scope`	String	Example: `all_branches`
`external_url`	String	Example: `https://www.example.com`
`hmac?`	Boolean	Example: `true`
`id`	Integer	Example: `100`
`name`	String	Example: `lorem ipsum`
`project_id`	Integer	Example: `101`
`protected_branches`	Array of APIEntitiesProtectedBranch	—
`timeout_minutes`	Integer	Example: `5`

APIEntitiesIssuableReferences

Property	Type	Description
`full`	String	Example: `test&6`
`relative`	String	Example: `&6`
`short`	String	Example: `&6`

APIEntitiesIssuableTimeStats

Property	Type	Description
`human_time_estimate`	String	Example: `3h 30m`
`human_total_time_spent`	String	Example: `1h`
`time_estimate`	Integer	Example: `12600`
`total_time_spent`	Integer	Example: `3600`

APIEntitiesMergeRequest

Property	Type	Description
`allow_collaboration`	Boolean	—
`allow_maintainer_to_push`	Boolean	—
`assignee`	APIEntitiesUserBasic	—
`assignees`	APIEntitiesUserBasic	—
`author`	APIEntitiesUserBasic	—
`blocking_discussions_resolved`	Boolean	—
`changes_count`	String	Example: `1`
`closed_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`closed_by`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2022-08-17T12:46:35.053Z`
`description`	String	Example: `Repellendus impedit et vel velit dignissimos.`
`description_html`	String	—
`detailed_merge_status`	String	Example: `mergeable`
`diff_refs`	APIEntitiesDiffRefs	—
`discussion_locked`	Boolean	—
`diverged_commits_count`	Integer	Example: `0`
`downvotes`	Integer	—
`draft`	Boolean	—
`first_contribution`	Boolean	—
`first_deployed_to_production_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`force_remove_source_branch`	Boolean	—
`has_conflicts`	Boolean	—
`head_pipeline`	APIEntitiesCiPipeline	—
`id`	Integer (int64)	Example: `84`
`iid`	Integer	Example: `14`
`imported`	Boolean	—
`imported_from`	String	Example: `bitbucket`
`labels`	Array of strings	—
`latest_build_finished_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`latest_build_started_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merge_after`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merge_commit_sha`	String	Example: `1234abcd`
`merge_error`	String	Example: `Merge error`
`merge_status`	String	Example: `unchecked`
`merge_user`	APIEntitiesUserBasic	—
`merge_when_pipeline_succeeds`	Boolean	—
`merged_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merged_by`	APIEntitiesUserBasic	—
`milestone`	APIEntitiesMilestone	—
`pipeline`	APIEntitiesCiPipelineBasic	—
`prepared_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`project_id`	Integer (int64)	Example: `4`
`rebase_in_progress`	Boolean	—
`reference`	String	Example: `!1`
`references`	APIEntitiesIssuableReferences	—
`reviewers`	APIEntitiesUserBasic	—
`sha`	String	Example: `1234abcd`
`should_remove_source_branch`	Boolean	—
`source_branch`	String	—
`source_project_id`	Integer (int64)	—
`squash`	Boolean	—
`squash_commit_sha`	String	Example: `1234abcd`
`squash_on_merge`	Boolean	—
`state`	String	Example: `closed`
`subscribed`	Boolean	—
`target_branch`	String	—
`target_project_id`	Integer (int64)	—
`task_completion_status`	APIEntitiesTaskCompletionStatus	—
`time_stats`	APIEntitiesIssuableTimeStats	—
`title`	String	Example: `Impedit et ut et dolores vero provident ullam est`
`title_html`	String	—
`updated_at`	String (date-time)	Example: `2022-11-14T17:22:01.470Z`
`upvotes`	Integer	—
`user`	Object	—
`user.can_merge`	Boolean	—
`user_notes_count`	Integer	—
`web_url`	String	Example: `https://gitlab.example.com/my-group/my-project/-/merge_requests/1`
`work_in_progress`	Boolean	—

APIEntitiesMergeRequestsExternalStatusCheck

Property	Type	Description
`error_reason`	String	Example: `Timeout error`
`external_url`	String	Example: `https://www.test.com`
`id`	Integer	Example: `1`
`name`	String	Example: `Security`
`status`	String	Example: `pending`

APIEntitiesMergeRequestsExternalStatusCheckResponse

Property	Type	Description
`external_status_check`	APIEntitiesExternalStatusCheck	—
`id`	Integer	Example: `1`
`merge_request`	APIEntitiesMergeRequest	—

APIEntitiesMilestone

Property	Type	Description
`created_at`	String	—
`description`	String	—
`due_date`	String	—
`expired`	Boolean	—
`group_id`	String	—
`id`	Integer (int64)	—
`iid`	Integer (int64)	—
`project_id`	Integer (int64)	—
`start_date`	String	—
`state`	String	—
`title`	String	—
`updated_at`	String	—
`web_url`	String	—

APIEntitiesProtectedBranch

Property	Type	Description
`allow_force_push`	Boolean	—
`id`	Integer (int64)	Example: `1`
`merge_access_levels`	Array of APIEntitiesProtectedRefAccess	—
`name`	String	Example: `main`
`push_access_levels`	Array of APIEntitiesProtectedRefAccess	—

APIEntitiesProtectedRefAccess

Property	Type	Description
`access_level`	Integer	Example: `40`
`access_level_description`	String	Example: `Maintainers`
`deploy_key_id`	Integer (int64)	Example: `1`
`group_id`	Integer	Example: `1`
`id`	Integer (int64)	Example: `1`
`user_id`	Integer	Example: `1`

APIEntitiesTaskCompletionStatus

Property	Type	Description
`completed_count`	Integer	Example: `3`
`count`	Integer	Example: `5`

APIEntitiesUserBasic

Property	Type	Description
`avatar_path`	String	Example: `/user/avatar/28/The-Big-Lebowski-400-400.png`
`avatar_url`	String	Example: `https://gravatar.com/avatar/1`
`custom_attributes`	Array of APIEntitiesCustomAttribute	—
`id`	Integer (int64)	Example: `1`
`locked`	Boolean	—
`name`	String	Example: `Administrator`
`public_email`	String	Example: `john@example.com`
`state`	String	Example: `active`
`username`	String	Example: `admin`
`web_url`	String	Example: `https://gitlab.example.com/root`

DetailedStatusEntity

Property	Type	Description
`action`	Object	—
`action.button_title`	String	Example: `Cancel this job`
`action.confirmation_message`	String	Example: `Are you sure?`
`action.icon`	String	Example: `cancel`
`action.method`	String	Example: `post`
`action.path`	String	Example: `/namespace1/project1/-/jobs/2/cancel`
`action.title`	String	Example: `Cancel`
`details_path`	String	Example: `/test-group/test-project/-/pipelines/287`
`favicon`	String	Example: `/assets/ci_favicons/favicon_status_success.png`
`group`	String	Example: `success`
`has_details`	Boolean	Example: `true`
`icon`	String	Example: `status_success`
`illustration`	Object	Example: `{"content":"This job depends on upstream jobs that need to succeed in order for this job to be triggered","image":"illustrations/empty-state/empty-job-not-triggered-md.svg","size":"","title":"This job has not been triggered yet"}`
`label`	String	Example: `passed`
`text`	String	Example: `passed`
`tooltip`	String	Example: `passed`

Get list of project external status checks

Create external status check

Update external status check by id

Delete external status check

Set status of an external status check

List status checks for a merge request

Retry failed external status check

Schemas

APIEntitiesCiPipeline

APIEntitiesCiPipelineBasic

APIEntitiesCustomAttribute

APIEntitiesDiffRefs

APIEntitiesExternalStatusCheck

APIEntitiesIssuableReferences

APIEntitiesIssuableTimeStats

APIEntitiesMergeRequest

APIEntitiesMergeRequestsExternalStatusCheck

APIEntitiesMergeRequestsExternalStatusCheckResponse

APIEntitiesMilestone

APIEntitiesProtectedBranch

APIEntitiesProtectedRefAccess

APIEntitiesTaskCompletionStatus

APIEntitiesUserBasic

DetailedStatusEntity

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error