Skip to content
forgit api docs

Update status of an external status check

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

Updates the status of an external status check for a specified merge request, informing 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 the Developer, Maintainer, or Owner role on the target project of the merge request. Any user with permission to approve the merge request can use this operation.

Authorizations

Section titled “ Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “ Path Parameters ”
id
required
string

ID of a project

Example 
1
merge_request_iid
required
integer

IID of a merge request

Example 
1

Request Body required

Section titled “ Request Body required ”
Media type application/json
object
external_status_check_id
required

ID of an external status check

integer
nullable
Example 
1
sha
required

SHA at HEAD of the source branch

string
nullable
Example 
5957a570eee0ac4580ec027fb874ad7514d1e576
status
required

Set to pending to mark the check as pending, passed to pass the check, or failed to fail it

string
>= 1 characters
Allowed values: passed failed pending

Responses

Section titled “ Responses ”

201

Section titled “ 201 ”

Created

Media type application/json
object
id
integer format: int64
merge_request
object
id
integer format: int64
iid
integer
project_id
integer format: int64
title
string
description
string
state
string
created_at
string format: date-time
updated_at
string format: date-time
merged_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
merge_user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
merged_at
string format: date-time
closed_by
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
closed_at
string format: date-time
title_html
string
description_html
string
target_branch
string
source_branch
string
user_notes_count
integer
upvotes
integer
downvotes
integer
author
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
assignees
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
assignee
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
reviewers
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
source_project_id
integer format: int64
target_project_id
integer format: int64
labels
Array<string>
draft
boolean
imported
boolean
imported_from
string
work_in_progress
boolean
milestone
object
id
integer format: int64
iid
integer format: int64
project_id
integer format: int64
group_id
string
title
string
description
string
state
string
created_at
string
updated_at
string
due_date
string
start_date
string
expired
boolean
web_url
string
merge_when_pipeline_succeeds
boolean
merge_status
string
detailed_merge_status
string
merge_after
string format: date-time
sha
string
merge_commit_sha
string
squash_commit_sha
string
discussion_locked
boolean
should_remove_source_branch
boolean
force_remove_source_branch
boolean
prepared_at
string format: date-time
allow_collaboration
boolean
allow_maintainer_to_push
boolean
reference
string
references
object
short
string
relative
string
full
string
web_url
string
time_stats
object
time_estimate
integer
total_time_spent
integer
human_time_estimate
string
human_total_time_spent
string
squash
boolean
squash_on_merge
boolean
task_completion_status
object
count
integer
completed_count
integer
has_conflicts
boolean
blocking_discussions_resolved
boolean
approvals_before_merge
integer
subscribed
boolean
changes_count
string
latest_build_started_at
string format: date-time
latest_build_finished_at
string format: date-time
first_deployed_to_production_at
string format: date-time
pipeline
object
id
integer format: int64
iid
integer
project_id
integer format: int64
sha
string
ref
string
status
string
source
string
created_at
string format: date-time
updated_at
string format: date-time
web_url
string
head_pipeline
object
id
integer format: int64
iid
integer
project_id
integer format: int64
sha
string
ref
string
status
string
source
string
created_at
string format: date-time
updated_at
string format: date-time
web_url
string
before_sha
string
tag
boolean
yaml_errors
string
user
object
id
integer format: int64
username
string
public_email
string
name
string
state
string
locked
boolean
avatar_url
string
avatar_path
string
custom_attributes
Array<object>
object
key
string
value
string
web_url
string
started_at
string format: date-time
finished_at
string format: date-time
committed_at
string format: date-time
duration

Time spent running in seconds

integer
queued_duration

Time spent enqueued in seconds

integer
coverage
number format: float
detailed_status
object
icon
string
text
string
label
string
group
string
tooltip
string
has_details
boolean
details_path
string
illustration
object
favicon
string
action
string
archived
boolean
diff_refs
object
base_sha
string
head_sha
string
start_sha
string
merge_error
string
rebase_in_progress
boolean
diverged_commits_count
integer
first_contribution
boolean
user
object
external_status_check
object
id
integer format: int64
name
string
project_id
integer format: int64
external_url
string
protected_branches
Array<object>
object
id
integer format: int64
name
string
push_access_levels
Array<object>
object
id
integer format: int64
access_level
integer
access_level_description
string
deploy_key_id
integer format: int64
user_id
integer format: int64
group_id
integer format: int64
member_role_id
integer format: int64
member_role_name
string
merge_access_levels
Array<object>
object
id
integer format: int64
access_level
integer
access_level_description
string
deploy_key_id
integer format: int64
user_id
integer format: int64
group_id
integer format: int64
member_role_id
integer format: int64
member_role_name
string
allow_force_push
boolean
unprotect_access_levels
Array<object>
object
id
integer format: int64
access_level
integer
access_level_description
string
deploy_key_id
integer format: int64
user_id
integer format: int64
group_id
integer format: int64
member_role_id
integer format: int64
member_role_name
string
code_owner_approval_required
boolean
inherited
boolean
hmac
boolean
Example 
{
  "id": 1,
  "merge_request": {
    "id": 84,
    "iid": 14,
    "project_id": 4,
    "title": "Impedit et ut et dolores vero provident ullam est",
    "description": "Repellendus impedit et vel velit dignissimos.",
    "state": "closed",
    "created_at": "2022-08-17T12:46:35.053Z",
    "updated_at": "2022-11-14T17:22:01.470Z",
    "merged_by": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "merge_user": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "merged_at": "2022-01-31T15:10:45.080Z",
    "closed_by": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "closed_at": "2022-01-31T15:10:45.080Z",
    "author": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "assignees": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "assignee": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "reviewers": {
      "id": 1,
      "username": "admin",
      "public_email": "john@example.com",
      "name": "Administrator",
      "state": "active",
      "avatar_url": "https://gravatar.com/avatar/1",
      "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
      "custom_attributes": [
        {
          "key": "foo",
          "value": "bar"
        }
      ],
      "web_url": "https://gitlab.example.com/root"
    },
    "imported_from": "bitbucket",
    "merge_status": "unchecked",
    "detailed_merge_status": "mergeable",
    "merge_after": "2022-01-31T15:10:45.080Z",
    "sha": "1234abcd",
    "merge_commit_sha": "1234abcd",
    "squash_commit_sha": "1234abcd",
    "prepared_at": "2022-01-31T15:10:45.080Z",
    "reference": "!1",
    "references": {
      "short": "&6",
      "relative": "&6",
      "full": "test&6"
    },
    "web_url": "https://gitlab.example.com/my-group/my-project/-/merge_requests/1",
    "time_stats": {
      "time_estimate": 12600,
      "total_time_spent": 3600,
      "human_time_estimate": "3h 30m",
      "human_total_time_spent": "1h"
    },
    "task_completion_status": {
      "count": 5,
      "completed_count": 3
    },
    "approvals_before_merge": 2,
    "changes_count": "1",
    "latest_build_started_at": "2022-01-31T15:10:45.080Z",
    "latest_build_finished_at": "2022-01-31T15:10:45.080Z",
    "first_deployed_to_production_at": "2022-01-31T15:10:45.080Z",
    "pipeline": {
      "id": 1,
      "iid": 2,
      "project_id": 3,
      "sha": "0ec9e58fdfca6cdd6652c083c9edb53abc0bad52",
      "ref": "feature-branch",
      "status": "success",
      "source": "push",
      "created_at": "2022-10-21T16:49:48.000+02:00",
      "updated_at": "2022-10-21T16:49:48.000+02:00",
      "web_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61"
    },
    "head_pipeline": {
      "id": 1,
      "iid": 2,
      "project_id": 3,
      "sha": "0ec9e58fdfca6cdd6652c083c9edb53abc0bad52",
      "ref": "feature-branch",
      "status": "success",
      "source": "push",
      "created_at": "2015-12-24T15:51:21.880Z",
      "updated_at": "2015-12-24T17:54:31.198Z",
      "web_url": "https://gitlab.example.com/gitlab-org/gitlab-foss/-/pipelines/61",
      "before_sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
      "tag": false,
      "yaml_errors": "widgets:build: needs 'widgets:test'",
      "user": {
        "id": 1,
        "username": "admin",
        "public_email": "john@example.com",
        "name": "Administrator",
        "state": "active",
        "avatar_url": "https://gravatar.com/avatar/1",
        "avatar_path": "/user/avatar/28/The-Big-Lebowski-400-400.png",
        "custom_attributes": [
          {
            "key": "foo",
            "value": "bar"
          }
        ],
        "web_url": "https://gitlab.example.com/root"
      },
      "started_at": "2015-12-24T17:54:30.733Z",
      "finished_at": "2015-12-24T17:54:31.198Z",
      "committed_at": "2015-12-24T15:51:21.880Z",
      "duration": 127,
      "queued_duration": 63,
      "coverage": 98.29,
      "detailed_status": {
        "icon": "status_success",
        "text": "passed",
        "label": "passed",
        "group": "success",
        "tooltip": "passed",
        "has_details": true,
        "details_path": "/test-group/test-project/-/pipelines/287",
        "illustration": {
          "image": "illustrations/empty-state/empty-job-not-triggered-md.svg",
          "size": "",
          "title": "This job has not been triggered yet",
          "content": "This job depends on upstream jobs that need to succeed in order for this job to be triggered"
        },
        "favicon": "/assets/ci_favicons/favicon_status_success.png"
      },
      "archived": false
    },
    "diff_refs": {
      "base_sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
      "head_sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0",
      "start_sha": "b83d6e391c22777fca1ed3012fce84f633d7fed0"
    },
    "merge_error": "Merge error",
    "diverged_commits_count": 0
  },
  "external_status_check": {
    "id": 1,
    "name": "QA",
    "project_id": 1,
    "external_url": "https://www.example.com",
    "protected_branches": [
      {
        "id": 1,
        "name": "main",
        "push_access_levels": [
          {
            "id": 1,
            "access_level": 40,
            "access_level_description": "Maintainers",
            "deploy_key_id": 1,
            "user_id": 1,
            "group_id": 1,
            "member_role_id": 42,
            "member_role_name": "Lead Developer"
          }
        ],
        "merge_access_levels": [
          {
            "id": 1,
            "access_level": 40,
            "access_level_description": "Maintainers",
            "deploy_key_id": 1,
            "user_id": 1,
            "group_id": 1,
            "member_role_id": 42,
            "member_role_name": "Lead Developer"
          }
        ],
        "unprotect_access_levels": [
          {
            "id": 1,
            "access_level": 40,
            "access_level_description": "Maintainers",
            "deploy_key_id": 1,
            "user_id": 1,
            "group_id": 1,
            "member_role_id": 42,
            "member_role_name": "Lead Developer"
          }
        ]
      }
    ],
    "hmac": true
  }
}

400

Section titled “ 400 ”

Bad Request

404

Section titled “ 404 ”

Not Found