Commits API

  • Tier: Free, Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Use the commits API to manage Git commits in GitLab repositories.

Responses

Some date fields in responses from this API are, or can appear to be, duplicated information:

  • The created_at field exists solely for consistency with other GitLab APIs. It is always identical to the committed_date field.
  • The committed_date and authored_date fields are generated from different sources, and may not be identical.

Pagination response headers

For performance reasons, GitLab does not return the following headers in Commits API responses:

  • x-total
  • x-total-pages

For more information, see issue 389582.

List repository commits

Get a list of repository commits in a project.

GET /projects/:id/repository/commits
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
allbooleanNoRetrieve every commit from the repository. If true, the ref_name parameter is ignored.
authorstringNoSearch commits by commit author.
first_parentbooleanNoIf true, follows only the first parent commit upon seeing a merge commit.
orderstringNoList commits in order. Possible values: default, topo. Defaults to default, the commits are shown in reverse chronological order.
pathstringNoThe file path.
ref_namestringNoThe name of a repository branch, tag or revision range, or if not given the default branch.
sincestringNoOnly commits after or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
trailersbooleanNoIf true, parses and includes Git trailers for every commit.
untilstringNoOnly commits before or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ.
with_statsbooleanNoIf true, retrieve stats about each commit.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
author_emailstringEmail address of the commit author.
author_namestringName of the commit author.
authored_datestringDate when the commit was authored.
committed_datestringDate when the commit was committed.
committer_emailstringEmail address of the commit committer.
committer_namestringName of the commit committer.
created_atstringDate when the commit was created (identical to committed_date).
extended_trailersobjectExtended Git trailers with all values.
idstringSHA of the commit.
messagestringFull commit message.
parent_idsarrayArray of parent commit SHAs.
short_idstringShort SHA of the commit.
titlestringTitle of the commit message.
trailersobjectGit trailers parsed from the commit message.
web_urlstringWeb URL of the commit.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits"

Example response:

[
  {
    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
    "short_id": "ed899a2f4b5",
    "title": "Replace sanitize with escape once",
    "author_name": "Example User",
    "author_email": "user@example.com",
    "authored_date": "2021-09-20T11:50:22.001+00:00",
    "committer_name": "Administrator",
    "committer_email": "admin@example.com",
    "committed_date": "2021-09-20T11:50:22.001+00:00",
    "created_at": "2021-09-20T11:50:22.001+00:00",
    "message": "Replace sanitize with escape once",
    "parent_ids": [
      "6104942438c14ec7bd21c6cd5bd995272b3faff6"
    ],
    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746",
    "trailers": {},
    "extended_trailers": {}
  },
  {
    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
    "short_id": "6104942438c",
    "title": "Sanitize for network graph",
    "author_name": "randx",
    "author_email": "user@example.com",
    "committer_name": "ExampleName",
    "committer_email": "user@example.com",
    "created_at": "2021-09-20T09:06:12.201+00:00",
    "message": "Sanitize for network graph\nCc: John Doe <johndoe@gitlab.com>\nCc: Jane Doe <janedoe@gitlab.com>",
    "parent_ids": [
      "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
    ],
    "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746",
    "trailers": {
      "Cc": "Jane Doe <janedoe@gitlab.com>"
    },
    "extended_trailers": {
      "Cc": [
        "John Doe <johndoe@gitlab.com>",
        "Jane Doe <janedoe@gitlab.com>"
      ]
    }
  }
]

Create a commit with multiple files and actions

Create a commit by posting a JSON payload

POST /projects/:id/repository/commits
AttributeTypeRequiredDescription
actions[]arrayYesAn array of action hashes to commit as a batch. See the next table for what attributes it can take.
branchstringYesName of the branch to commit into. To create a new branch, also provide either start_branch or start_sha, and optionally start_project.
commit_messagestringYesCommit message.
idinteger or stringYesThe ID or URL-encoded path of the project.
author_emailstringNoSpecify the commit author’s email address.
author_namestringNoSpecify the commit author’s name.
forcebooleanNoIf true, overwrites the target branch with a new commit based on the start_branch or start_sha.
start_branchstringNoName of the branch to start the new branch from.
start_projectinteger or stringNoThe project ID or URL-encoded path of the project to start the new branch from. Defaults to the value of id.
start_shastringNoSHA of the commit to start the new branch from.
statsbooleanNoInclude commit stats. Default is true.
actions[] AttributeTypeRequiredDescription
actionstringYesThe action to perform: create, delete, move, update, or chmod.
file_pathstringYesFull path to the file. For example: lib/class.rb.
contentstringNoFile content, required for all except delete, chmod, and move. Move actions that do not specify content preserve the existing file content, and any other value of content overwrites the file content.
encodingstringNotext or base64. text is default.
execute_filemodebooleanNoIf true, enables the execute flag on the file. If false, disables it. Only considered for chmod action.
last_commit_idstringNoLast known file commit ID. Only considered in update, move, and delete actions.
previous_pathstringNoOriginal full path to the file being moved. For example lib/class1.rb. Only considered for move action.

If successful, returns 201 Created and the following response attributes:

AttributeTypeDescription
author_emailstringEmail address of the commit author.
author_namestringName of the commit author.
authored_datestringDate when the commit was authored.
committed_datestringDate when the commit was committed.
committer_emailstringEmail address of the commit committer.
committer_namestringName of the commit committer.
created_atstringDate when the commit was created.
idstringSHA of the created commit.
messagestringFull commit message.
parent_idsarrayArray of parent commit SHAs.
short_idstringShort SHA of the created commit.
statsobjectStatistics about the commit (additions, deletions, total).
statusstringStatus of the commit.
titlestringTitle of the commit message.
web_urlstringWeb URL of the commit.
PAYLOAD=$(cat << 'JSON'
{
  "branch": "main",
  "commit_message": "some commit message",
  "actions": [
    {
      "action": "create",
      "file_path": "foo/bar",
      "content": "some content"
    },
    {
      "action": "delete",
      "file_path": "foo/bar2"
    },
    {
      "action": "move",
      "file_path": "foo/bar3",
      "previous_path": "foo/bar4",
      "content": "some content"
    },
    {
      "action": "update",
      "file_path": "foo/bar5",
      "content": "new content"
    },
    {
      "action": "chmod",
      "file_path": "foo/bar5",
      "execute_filemode": true
    }
  ]
}
JSON
)
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --header "Content-Type: application/json" \
  --data "$PAYLOAD" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits"

Example response:

{
  "id": "ed899a2f4b50b4370feeea94676502b42383c746",
  "short_id": "ed899a2f4b5",
  "title": "some commit message",
  "author_name": "Example User",
  "author_email": "user@example.com",
  "committer_name": "Example User",
  "committer_email": "user@example.com",
  "created_at": "2016-09-20T09:26:24.000-07:00",
  "message": "some commit message",
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
  ],
  "committed_date": "2016-09-20T09:26:24.000-07:00",
  "authored_date": "2016-09-20T09:26:24.000-07:00",
  "stats": {
    "additions": 2,
    "deletions": 2,
    "total": 4
  },
  "status": null,
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
}

GitLab supports form encoding. The following is an example using Commit API with form encoding:

curl --request POST \
     --form "branch=main" \
     --form "commit_message=some commit message" \
     --form "start_branch=main" \
     --form "actions[][action]=create" \
     --form "actions[][file_path]=foo/bar" \
     --form "actions[][content]=</path/to/local.file" \
     --form "actions[][action]=delete" \
     --form "actions[][file_path]=foo/bar2" \
     --form "actions[][action]=move" \
     --form "actions[][file_path]=foo/bar3" \
     --form "actions[][previous_path]=foo/bar4" \
     --form "actions[][content]=</path/to/local1.file" \
     --form "actions[][action]=update" \
     --form "actions[][file_path]=foo/bar5" \
     --form "actions[][content]=</path/to/local2.file" \
     --form "actions[][action]=chmod" \
     --form "actions[][file_path]=foo/bar5" \
     --form "actions[][execute_filemode]=true" \
     --header "PRIVATE-TOKEN: <your_access_token>" \
     --url "https://gitlab.example.com/api/v4/projects/1/repository/commits"

Get a single commit

Get a specific commit identified by the commit hash or name of a branch or tag.

GET /projects/:id/repository/commits/:sha

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash or name of a repository branch or tag.
statsbooleanNoInclude commit stats. Default is true.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
author_emailstringEmail address of the commit author.
author_namestringName of the commit author.
authored_datestringDate when the commit was authored.
committed_datestringDate when the commit was committed.
committer_emailstringEmail address of the commit committer.
committer_namestringName of the commit committer.
created_atstringDate when the commit was created.
idstringSHA of the commit.
last_pipelineobjectInformation about the last pipeline for this commit.
messagestringFull commit message.
parent_idsarrayArray of parent commit SHAs.
short_idstringShort SHA of the commit.
statsobjectStatistics about the commit (additions, deletions, total).
statusstringStatus of the commit.
titlestringTitle of the commit message.
web_urlstringWeb URL of the commit.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main"

Example response:

{
  "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
  "short_id": "6104942438c",
  "title": "Sanitize for network graph",
  "author_name": "randx",
  "author_email": "user@example.com",
  "committer_name": "Dmitriy",
  "committer_email": "user@example.com",
  "created_at": "2021-09-20T09:06:12.300+03:00",
  "message": "Sanitize for network graph",
  "committed_date": "2021-09-20T09:06:12.300+03:00",
  "authored_date": "2021-09-20T09:06:12.420+03:00",
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
  ],
  "last_pipeline": {
    "id": 8,
    "ref": "main",
    "sha": "2dc6aa325a317eda67812f05600bdf0fcdc70ab0",
    "status": "created"
  },
  "stats": {
    "additions": 15,
    "deletions": 10,
    "total": 25
  },
  "status": "running",
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/6104942438c14ec7bd21c6cd5bd995272b3faff6"
}

Get references a commit is pushed to

Get all references (from branches or tags) a commit is pushed to. The pagination parameters page and per_page can be used to restrict the list of references.

GET /projects/:id/repository/commits/:sha/refs

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash.
typestringNoThe scope of commits. Possible values branch, tag, all. Default is all.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
namestringName of the branch or tag.
typestringType of reference (branch or tag).
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/refs?type=all"

Example response:

[
  {
    "type": "branch",
    "name": "'test'"
  },
  {
    "type": "branch",
    "name": "add-balsamiq-file"
  },
  {
    "type": "branch",
    "name": "wip"
  },
  {
    "type": "tag",
    "name": "v1.1.0"
  }
]

Get commit sequence

Get the sequence number of a commit in a project by following the parent links from the given commit.

This API provides essentially the same features as the git rev-list --count command for a given commit SHA.

GET /projects/:id/repository/commits/:sha/sequence

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash.
first_parentbooleanNoIf true, follows only the first parent commit upon seeing a merge commit.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
countintegerSequence number of the commit.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/5937ac0a7beb003549fc5fd26fc247adbce4a52e/sequence"

Example response:

{
  "count": 632
}

Cherry-pick a commit

Cherry-picks a commit to a given branch.

POST /projects/:id/repository/commits/:sha/cherry_pick

Parameters:

AttributeTypeRequiredDescription
branchstringYesThe name of the branch.
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash.
dry_runbooleanNoIf true, does not commit any changes. Default is false.
messagestringNoA custom commit message to use for the new commit.

If successful, returns 201 Created and the following response attributes:

AttributeTypeDescription
author_emailstringEmail address of the original commit author.
author_namestringName of the original commit author.
authored_datestringDate when the original commit was authored.
committed_datestringDate when the cherry-picked commit was committed.
committer_emailstringEmail address of the cherry-pick committer.
committer_namestringName of the cherry-pick committer.
created_atstringDate when the cherry-picked commit was created.
idstringSHA of the cherry-picked commit.
messagestringFull commit message.
parent_idsarrayArray of parent commit SHAs.
short_idstringShort SHA of the cherry-picked commit.
titlestringTitle of the commit message.
web_urlstringWeb URL of the cherry-picked commit.
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=main" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/cherry_pick"

Example response:

{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "author_name": "Example User",
  "author_email": "user@example.com",
  "authored_date": "2016-12-12T20:10:39.000+01:00",
  "created_at": "2016-12-12T20:10:39.000+01:00",
  "committer_name": "Administrator",
  "committer_email": "admin@example.com",
  "committed_date": "2016-12-12T20:10:39.000+01:00",
  "title": "Feature added",
  "message": "Feature added\n\nSigned-off-by: Example User <user@example.com>\n",
  "parent_ids": [
    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
  ],
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"
}

In the event of a failed cherry-pick, the response provides context about why:

{
  "message": "Sorry, we cannot cherry-pick this commit automatically. This commit may already have been cherry-picked, or a more recent commit may have updated some of its content.",
  "error_code": "empty"
}

In this case, the cherry-pick failed because the changeset was empty and likely indicates that the commit already exists in the target branch. The other possible error code is conflict, which indicates that there was a merge conflict.

When dry_run is enabled, the server attempts to apply the cherry-pick but not actually commit any resulting changes. If the cherry-pick applies cleanly, the API responds with 200 OK:

{
  "dry_run": "success"
}

In the event of a failure, an error displays that is identical to a failure without dry run.

Revert a commit

Reverts a commit in a given branch.

POST /projects/:id/repository/commits/:sha/revert

Parameters:

AttributeTypeRequiredDescription
branchstringYesTarget branch name.
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesCommit SHA to revert.
dry_runbooleanNoIf true, does not commit any changes. Default is false.

If successful, returns 201 Created and the following response attributes:

AttributeTypeDescription
author_emailstringEmail address of the revert commit author.
author_namestringName of the revert commit author.
authored_datestringDate when the revert commit was authored.
committed_datestringDate when the revert commit was committed.
committer_emailstringEmail address of the revert commit committer.
committer_namestringName of the revert commit committer.
created_atstringDate when the revert commit was created.
idstringSHA of the revert commit.
messagestringFull revert commit message.
parent_idsarrayArray of parent commit SHAs.
short_idstringShort SHA of the revert commit.
titlestringTitle of the revert commit message.
web_urlstringWeb URL of the revert commit.
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "branch=main" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/a738f717824ff53aebad8b090c1b79a14f2bd9e8/revert"

Example response:

{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "title": "Revert \"Feature added\"",
  "created_at": "2018-11-08T15:55:26.000Z",
  "parent_ids": [
    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
  ],
  "message": "Revert \"Feature added\"\n\nThis reverts commit a738f717824ff53aebad8b090c1b79a14f2bd9e8",
  "author_name": "Administrator",
  "author_email": "admin@example.com",
  "authored_date": "2018-11-08T15:55:26.000Z",
  "committer_name": "Administrator",
  "committer_email": "admin@example.com",
  "committed_date": "2018-11-08T15:55:26.000Z",
  "web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/8b090c1b79a14f2bd9e8a738f717824ff53aebad"
}

In the event of a failed revert, the response provides context about why:

{
  "message": "Sorry, we cannot revert this commit automatically. This commit may already have been reverted, or a more recent commit may have updated some of its content.",
  "error_code": "conflict"
}

In this case, the revert failed because the attempted revert generated a merge conflict. The other possible error code is empty, which indicates that the changeset was empty, likely due to the change having already been reverted.

When dry_run is enabled, the server attempts to apply the revert but not actually commit any resulting changes. If the revert applies cleanly, the API responds with 200 OK:

{
  "dry_run": "success"
}

In the event of a failure, an error displays that is identical to a failure without dry run.

Get commit diff

Get the diff of a commit in a project.

GET /projects/:id/repository/commits/:sha/diff

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash or name of a repository branch or tag.
unidiffbooleanNoIf true, presents diffs in the unified diff format. Default is false. Introduced in GitLab 16.5.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
a_modestringFile mode before the change.
b_modestringFile mode after the change.
deleted_filebooleanIf true, the file was deleted.
diffstringThe diff content.
new_filebooleanIf true, this is a new file.
new_pathstringNew path of the file.
old_pathstringOld path of the file.
renamed_filebooleanIf true, the file was renamed.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/diff"

Example response:

[
  {
    "diff": "@@ -71,6 +71,8 @@\n sudo -u git -H bundle exec rake migrate_keys RAILS_ENV=production\n sudo -u git -H bundle exec rake migrate_inline_notes RAILS_ENV=production\n \n+sudo -u git -H bundle exec rake gitlab:assets:compile RAILS_ENV=production\n+\n ```\n \n ### 6. Update config files",
    "new_path": "doc/update/5.4-to-6.0.md",
    "old_path": "doc/update/5.4-to-6.0.md",
    "a_mode": null,
    "b_mode": "100644",
    "new_file": false,
    "renamed_file": false,
    "deleted_file": false
  }
]

Get commit comments

Get the comments of a commit in a project.

GET /projects/:id/repository/commits/:sha/comments

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash or name of a repository branch or tag.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
authorobjectInformation about the comment author.
notestringThe comment text.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/main/comments"

Example response:

[
  {
    "note": "this code is really nice",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "admin@local.host",
      "name": "Administrator",
      "state": "active",
      "created_at": "2014-03-06T08:17:35.000Z"
    }
  }
]

Post comment to commit

Adds a comment to a commit.

To post a comment in a particular line of a particular file, you must specify the full commit SHA, the path, the line, and line_type should be new.

The comment is added at the end of the last commit if at least one of the following cases is valid:

  • the sha is instead a branch or a tag and the line or path are invalid
  • the line number is invalid (does not exist)
  • the path is invalid (does not exist)

In any of the previous cases, the response of line, line_type and path is set to null.

For other approaches to commenting on a merge request, see Create new merge request note in the Notes API, and Create a new thread in the merge request diff in the Discussions API.

POST /projects/:id/repository/commits/:sha/comments
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
notestringYesThe text of the comment.
shastringYesThe commit SHA or name of a repository branch or tag.
lineintegerNoThe line number where the comment should be placed.
line_typestringNoThe line type. Takes new or old as arguments.
pathstringNoThe file path relative to the repository.

If successful, returns 201 Created and the following response attributes:

AttributeTypeDescription
authorobjectInformation about the comment author.
created_atstringDate when the comment was created.
line_typestringType of line the comment is on.
lineintegerLine number where the comment is placed.
notestringThe comment text.
pathstringFile path relative to the repository.
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --form "note=Nice picture\!" \
  --form "path=README.md" \
  --form "line=11" \
  --form "line_type=new" \
  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments"

Example response:

{
  "author": {
    "web_url": "https://gitlab.example.com/janedoe",
    "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
    "username": "janedoe",
    "state": "active",
    "name": "Jane Doe",
    "id": 28
  },
  "created_at": "2016-01-19T09:44:55.600Z",
  "line_type": "new",
  "path": "README.md",
  "line": 11,
  "note": "Nice picture!"
}

Get commit discussions

Get the discussions of a commit in a project.

GET /projects/:id/repository/commits/:sha/discussions

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash or name of a repository branch or tag.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
idstringID of the discussion.
individual_notebooleanIf true, the discussion is an individual note.
notesarrayArray of notes in the discussion.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/4604744a1c64de00ff62e1e8a6766919923d2b41/discussions"

Example response:

[
  {
    "id": "4604744a1c64de00ff62e1e8a6766919923d2b41",
    "individual_note": true,
    "notes": [
      {
        "id": 334686748,
        "type": null,
        "body": "Nice piece of code!",
        "attachment": null,
        "author": {
          "id": 28,
          "name": "Jane Doe",
          "username": "janedoe",
          "web_url": "https://gitlab.example.com/janedoe",
          "state": "active",
          "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png"
        },
        "created_at": "2020-04-30T18:48:11.432Z",
        "updated_at": "2020-04-30T18:48:11.432Z",
        "system": false,
        "noteable_id": null,
        "noteable_type": "Commit",
        "resolvable": false,
        "confidential": null,
        "noteable_iid": null,
        "commands_changes": {}
      }
    ]
  }
]

Commit status

The commit status API for use with GitLab.

List commit statuses

List the statuses of a commit in a project. The pagination parameters page and per_page can be used to restrict the list of references.

GET /projects/:id/repository/commits/:sha/statuses
AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.
shastringYesHash of the commit.
allbooleanNoIf true, include all statuses instead of latest only. Default is false.
namestringNoFilter statuses by job name. For example, bundler:audit.
order_bystringNoValues for sorting statuses. Valid values are id and pipeline_id. Default is id.
pipeline_idintegerNoFilter statuses by pipeline ID. For example, 1234.
refstringNoName of the branch or tag. Default is the default branch.
sortstringNoSort statuses in ascending or descending order. Valid values are asc and desc. Default is asc.
stagestringNoFilter statuses by build stage. For example, test.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
allow_failurebooleanIf true, the status allows failure.
authorobjectInformation about the status author.
created_atstringDate when the status was created.
descriptionstringDescription of the status.
finished_atstringDate when the status was finished.
idintegerID of the status.
namestringName of the status.
refstringReference (branch or tag) of the commit.
shastringSHA of the commit.
started_atstringDate when the status was started.
statusstringStatus of the commit.
target_urlstringTarget URL associated with the status.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/statuses"

Example response:

[
  ...
  {
    "status": "pending",
    "created_at": "2016-01-19T08:40:25.934Z",
    "started_at": null,
    "name": "bundler:audit",
    "allow_failure": true,
    "author": {
      "username": "janedoe",
      "state": "active",
      "web_url": "https://gitlab.example.com/janedoe",
      "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
      "id": 28,
      "name": "Jane Doe"
    },
    "description": null,
    "sha": "18f3e63d05582537db6d183d9d557be09e1f90c8",
    "target_url": "https://gitlab.example.com/janedoe/gitlab-foss/builds/91",
    "finished_at": null,
    "id": 91,
    "ref": "main"
  },
  {
    "started_at": null,
    "name": "test",
    "allow_failure": false,
    "status": "pending",
    "created_at": "2016-01-19T08:40:25.832Z",
    "target_url": "https://gitlab.example.com/janedoe/gitlab-foss/builds/90",
    "id": 90,
    "finished_at": null,
    "ref": "main",
    "sha": "18f3e63d05582537db6d183d9d557be09e1f90c8",
    "author": {
      "id": 28,
      "name": "Jane Doe",
      "username": "janedoe",
      "web_url": "https://gitlab.example.com/janedoe",
      "state": "active",
      "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png"
    },
    "description": null
  }
  ...
]

Set commit pipeline status

Add or update the pipeline status of a commit. If the commit is associated with a merge request, the API call must target the commit in the merge request’s source branch.

If a pipeline already exists and it exceeds the maximum number of jobs in a single pipeline limit:

  • If pipeline_id is specified, a 422 error is returned: The number of jobs has exceeded the limit.
  • Otherwise, a new pipeline is created.
POST /projects/:id/statuses/:sha
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit SHA.
statestringYesThe state of the status. Can be one of the following: pending, running, success, failed, canceled, skipped.
coveragefloatNoThe total code coverage.
descriptionstringNoThe short description of the status. Must be 255 characters or fewer.
name or contextstringNoThe label to differentiate this status from the status of other systems. Default value is default.
pipeline_idintegerNoThe ID of the pipeline to set status. Use in case of several pipeline on same SHA.
refstringNoThe ref (branch or tag) to which the status refers. Must be 255 characters or fewer.
target_urlstringNoThe target URL to associate with this status. Must be 255 characters or fewer.

If successful, returns 201 Created and the following response attributes:

AttributeTypeDescription
allow_failurebooleanIf true, the status allows failure.
authorobjectInformation about the status author.
coveragefloatCode coverage percentage.
created_atstringDate when the status was created.
descriptionstringDescription of the status.
finished_atstringDate when the status was finished.
idintegerID of the status.
namestringName of the status.
refstringReference (branch or tag) of the commit.
shastringSHA of the commit.
started_atstringDate when the status was started.
statusstringStatus of the commit.
target_urlstringTarget URL associated with the status.
curl --request POST \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"

Example response:

{
  "author": {
    "web_url": "https://gitlab.example.com/janedoe",
    "name": "Jane Doe",
    "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
    "username": "janedoe",
    "state": "active",
    "id": 28
  },
  "name": "default",
  "sha": "18f3e63d05582537db6d183d9d557be09e1f90c8",
  "status": "success",
  "coverage": 100.0,
  "description": null,
  "id": 93,
  "target_url": null,
  "ref": null,
  "started_at": null,
  "created_at": "2016-01-19T09:05:50.355Z",
  "allow_failure": false,
  "finished_at": "2016-01-19T09:05:50.365Z"
}

List merge requests associated with a commit

Returns information about the merge request that originally introduced a specific commit.

GET /projects/:id/repository/commits/:sha/merge_requests
AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit SHA.
statestringNoReturns merge requests with the specified state: opened, closed, locked, or merged. Omit this parameter to get all merge requests regardless of state.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
assigneeobjectInformation about the merge request assignee.
authorobjectInformation about the merge request author.
created_atstringDate when the merge request was created.
descriptionstringDescription of the merge request.
discussion_lockedbooleanIf true, discussions are locked.
downvotesintegerNumber of downvotes.
draftbooleanIf true, the merge request is a draft.
force_remove_source_branchbooleanIf true, forces source branch removal.
idintegerID of the merge request.
iidintegerInternal ID of the merge request.
labelsarrayLabels associated with the merge request.
merge_commit_shastringSHA of the merge commit.
merge_statusstringMerge status of the merge request.
merge_when_pipeline_succeedsbooleanIf true, merges when pipeline succeeds.
milestoneobjectMilestone associated with the merge request.
project_idintegerID of the project.
shastringSHA of the merge request.
should_remove_source_branchbooleanIf true, removes source branch after merge.
source_branchstringSource branch of the merge request.
source_project_idintegerID of the source project.
squash_commit_shastringSHA of the squash commit.
statestringState of the merge request.
target_branchstringTarget branch of the merge request.
target_project_idintegerID of the target project.
time_statsobjectTime tracking statistics.
titlestringTitle of the merge request.
updated_atstringDate when the merge request was last updated.
upvotesintegerNumber of upvotes.
user_notes_countintegerNumber of user notes.
web_urlstringWeb URL of the merge request.
work_in_progressbooleanIf true, the merge request is set as work in progress.
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests?state=opened"

Example response:

[
  {
    "id": 45,
    "iid": 1,
    "project_id": 35,
    "title": "Add new file",
    "description": "",
    "state": "opened",
    "created_at": "2018-03-26T17:26:30.916Z",
    "updated_at": "2018-03-26T17:26:30.916Z",
    "target_branch": "main",
    "source_branch": "test-branch",
    "upvotes": 0,
    "downvotes": 0,
    "author": {
      "web_url": "https://gitlab.example.com/janedoe",
      "name": "Jane Doe",
      "avatar_url": "https://gitlab.example.com/uploads/user/avatar/28/jane-doe-400-400.png",
      "username": "janedoe",
      "state": "active",
      "id": 28
    },
    "assignee": null,
    "source_project_id": 35,
    "target_project_id": 35,
    "labels": [],
    "draft": false,
    "work_in_progress": false,
    "milestone": null,
    "merge_when_pipeline_succeeds": false,
    "merge_status": "can_be_merged",
    "sha": "af5b13261899fb2c0db30abdd0af8b07cb44fdc5",
    "merge_commit_sha": null,
    "squash_commit_sha": null,
    "user_notes_count": 0,
    "discussion_locked": null,
    "should_remove_source_branch": null,
    "force_remove_source_branch": false,
    "web_url": "https://gitlab.example.com/root/test-project/merge_requests/1",
    "time_stats": {
      "time_estimate": 0,
      "total_time_spent": 0,
      "human_time_estimate": null,
      "human_total_time_spent": null
    }
  }
]

Get commit signature

Get the signature from a commit, if it is signed. For unsigned commits, it results in a 404 response.

GET /projects/:id/repository/commits/:sha/signature

Parameters:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the project.
shastringYesThe commit hash or name of a repository branch or tag.

If successful, returns 200 OK and the following response attributes:

AttributeTypeDescription
commit_sourcestringSource of the commit.
gpg_key_idintegerID of the GPG key (for PGP signatures).
gpg_key_primary_keyidstringPrimary key ID of the GPG key.
gpg_key_subkey_idstringSubkey ID of the GPG key.
gpg_key_user_emailstringEmail address associated with the GPG key.
gpg_key_user_namestringUser name associated with the GPG key.
keyobjectSSH key information (for SSH signatures).
signature_typestringType of signature (PGP, SSH, or X509).
verification_statusstringVerification status of the signature.
x509_certificateobjectX.509 certificate information (for X.509 signatures).
curl --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/projects/1/repository/commits/da738facbc19eb2fc2cef57c49be0e6038570352/signature"

Example response if commit is GPG signed:

{
  "signature_type": "PGP",
  "verification_status": "verified",
  "gpg_key_id": 1,
  "gpg_key_primary_keyid": "8254AAB3FBD54AC9",
  "gpg_key_user_name": "John Doe",
  "gpg_key_user_email": "johndoe@example.com",
  "gpg_key_subkey_id": null,
  "commit_source": "gitaly"
}

Example response if commit is signed with SSH:

{
  "signature_type": "SSH",
  "verification_status": "verified",
  "key": {
    "id": 11,
    "title": "Key",
    "created_at": "2023-05-08T09:12:38.503Z",
    "expires_at": "2024-05-07T00:00:00.000Z",
    "key": "ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAILZzYDq6DhLp3aX84DGIV3F6Vf+Ae4yCTTz7RnqMJOlR MyKey)",
    "usage_type": "auth_and_signing"
  },
  "commit_source": "gitaly"
}

Example response if commit is X.509 signed:

{
  "signature_type": "X509",
  "verification_status": "unverified",
  "x509_certificate": {
    "id": 1,
    "subject": "CN=gitlab@example.org,OU=Example,O=World",
    "subject_key_identifier": "BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC:BC",
    "email": "gitlab@example.org",
    "serial_number": 278969561018901340486471282831158785578,
    "certificate_status": "good",
    "x509_issuer": {
      "id": 1,
      "subject": "CN=PKI,OU=Example,O=World",
      "subject_key_identifier": "AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB:AB",
      "crl_url": "http://example.com/pki.crl"
    }
  },
  "commit_source": "gitaly"
}

Example response if commit is unsigned:

{
  "message": "404 GPG Signature Not Found"
}