Commits

Use this API to manage Git commits.

List all repository commits

GET /api/v4/projects/{id}/repository/commits

Lists all commits for a specified project repository.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`ref_name` Query	String	Name of a repository branch, tag, or revision range. Uses the default branch if not given Example: `v1.1.0`
`since` Query	String (date-time)	Only commits after or on this date are returned Example: `2021-09-20T11:50:22.001Z`
`until` Query	String (date-time)	Only commits before or on this date are returned Example: `2021-09-20T11:50:22.001Z`
`path` Query	String	File path relative to the repository Example: `README.md`
`follow` Query	Boolean	If `true`, follows file renames when filtering commits by `path` and returns commits for the file even if it was renamed. If `false`, returns only commits where the file existed at its current path. Used only when `path` specifies a single file
`author` Query	String	Filter commits by commit author Example: `John Smith`
`all` Query	Boolean	If `true`, retrieves every commit from the repository and ignores the `ref_name` parameter
`with_stats` Query	Boolean	If `true`, includes statistics for each commit in the response
`first_parent` Query	Boolean	If `true`, follows only the first parent commit upon seeing a merge commit
`order` Query	String	Order in which to list commits, either reverse chronological or topological Allowed values: `default`, `topo` Default: `default`
`trailers` Query	Boolean	If `true`, parses and includes Git trailers for every commit Default: `false`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`pagination` Query	String	Specify the pagination method Allowed values: `legacy`, `keyset` Default: `legacy`
`page_token` Query	String	Record from which to start the keyset pagination

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCommit
`400`	Bad request	—
`401`	Unauthorized	—
`404`	Not found	—

Create a commit

POST /api/v4/projects/{id}/repository/commits

This feature was introduced in GitLab 8.13

Parameters

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

Request body (multipart/form-data)

Property	Type	Description
`file` Required	String (binary)	The commit content to be created (generated by Multipart middleware)

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommitDetail
`400`	Bad request	—
`401`	Unauthorized	—
`403`	Forbidden	—
`404`	Not found	—

Retrieve a commit

GET /api/v4/projects/{id}/repository/commits/{sha}

Retrieves a specified commit identified by the commit hash or name of a branch or tag.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA or name of a repository branch or tag
`stats` Query	Boolean	If `true`, includes commit statistics in the response Default: `true`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommitDetail
`400`	Bad Request	—
`404`	Not found	—

Cherry-pick a commit

POST /api/v4/projects/{id}/repository/commits/{sha}/cherry_pick

Cherry-picks a commit to a specified branch.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA, or name of a repository branch or tag, to cherry-pick

Request body (application/json)

Property	Type	Description
`branch` Required	String	Name of the branch Example: `master`
`dry_run`	Boolean	If `true`, does not commit any changes Default: `false`
`message`	String	Custom commit message to use for the new commit Example: `Initial commit`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommit
`400`	Bad request	—
`404`	Not found	—

List all commit comments

GET /api/v4/projects/{id}/repository/commits/{sha}/comments

Lists all the comments of a commit in a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`sha` Path, required	String	Commit SHA or name of a repository branch or tag

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesCommitNote
`400`	Bad Request	—
`404`	Not found	—

Create a comment on a commit

POST /api/v4/projects/{id}/repository/commits/{sha}/comments

Creates a comment on a commit. To comment on a specific line in a file, specify the full commit SHA, path, line, and set line_type to new.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA or name of a repository branch or tag

Request body (application/json)

Property	Type	Description
`line` Required	Integer	Line number where the comment should be placed Example: `11`
`line_type` Required	String	Line type Allowed values: `new`, `old` Default: `new` Minimum length: `1`
`note` Required	String	Text of the comment Example: `Nice code!`
`path`	String	File path relative to the repository Example: `doc/update/5.4-to-6.0.md`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommitNote
`400`	Bad request	—
`404`	Not found	—

Retrieve a commit diff

GET /api/v4/projects/{id}/repository/commits/{sha}/diff

Retrieves the diff of a commit in a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA or name of a repository branch or tag
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`
`unidiff` Query	Boolean	If `true`, presents diffs in the unified diff format Default: `false`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesDiff
`400`	Bad Request	—
`404`	Not found	—

List all merge requests associated with a commit

GET /api/v4/projects/{id}/repository/commits/{sha}/merge_requests

Lists all merge requests associated with a specified commit.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA or name of a repository branch or tag
`state` Query	String	Filter merge requests by state: `opened`, `closed`, `locked`, or `merged`. If omitted, merge requests of all states are returned. Introduced in GitLab 18.2 Example: `merged`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesMergeRequestBasic
`400`	Bad Request	—
`404`	Not found	—

List all references a commit is pushed to

GET /api/v4/projects/{id}/repository/commits/{sha}/refs

Lists 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.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA
`type` Query	String	Type of references to return for the commit Allowed values: `branch`, `tag`, `all` Default: `all`
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of APIEntitiesBasicRef
`400`	Bad Request	—
`404`	Not found	—

Revert a commit

POST /api/v4/projects/{id}/repository/commits/{sha}/revert

Reverts a commit in a specified branch.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA to revert

Request body (application/json)

Property	Type	Description
`branch` Required	String	Name of the target branch Example: `master`
`dry_run`	Boolean	If `true`, does not commit any changes Default: `false`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommit
`400`	Bad request	—
`404`	Not found	—

Retrieve a commit sequence

GET /api/v4/projects/{id}/repository/commits/{sha}/sequence

Retrieves the commit sequence for a specified commit.

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA
`first_parent` Query	Boolean	If `true`, follows only the first parent commit upon seeing a merge commit Default: `false`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommitSequence
`400`	Bad Request	—
`404`	Not found	—

Retrieve a commit signature

GET /api/v4/projects/{id}/repository/commits/{sha}/signature

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

Parameters

Name	Type	Description
`id` Path, required	String or integer	ID or URL-encoded path of the project
`sha` Path, required	String	Commit SHA or name of a repository branch or tag

Responses

Code	Description	Schema
`200`	OK	APIEntitiesCommitSignature
`400`	Bad Request	—
`404`	Not found	—

Schemas

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

APIEntitiesBasicRef

Property	Type	Description
`name`	String	Example: `v1.1.0`
`type`	String	Example: `tag`

APIEntitiesCommit

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`short_id`	String	Example: `2695effb`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCommitDetail

Property	Type	Description
`author_email`	String	Example: `john@example.com`
`author_name`	String	Example: `John Smith`
`authored_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committed_date`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`committer_email`	String	Example: `jack@example.com`
`committer_name`	String	Example: `Jack Smith`
`created_at`	String (date-time)	Example: `2017-07-26T11:08:53.000+02:00`
`extended_trailers`	Object	Example: `{"Signed-off-by":["John Doe \u003cjohndoe@gitlab.com\u003e","Jane Doe \u003cjanedoe@gitlab.com\u003e"]}`
`id`	String	Example: `2695effb5807a22ff3d138d593fd856244e155e7`
`last_pipeline`	Object	—
`message`	String	Example: `Initial commit`
`parent_ids`	Array of strings	Example: `["2a4b78934375d7f53875269ffd4f45fd83a84ebe"]`
`project_id`	Integer (int64)	Example: `1`
`short_id`	String	Example: `2695effb`
`stats`	APIEntitiesCommitStats	—
`status`	String	Example: `success`
`title`	String	Example: `Initial commit`
`trailers`	Object	Example: `{"Merged-By":"Jane Doe janedoe@gitlab.com"}`
`web_url`	String	Example: `https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746`

APIEntitiesCommitNote

Property	Type	Description
`author`	APIEntitiesUserBasic	—
`created_at`	String (date-time)	Example: `2016-01-19T09:44:55.600Z`
`line`	Integer	Example: `11`
`line_type`	String	Example: `new`
`note`	String	Example: `this doc is really nice`
`path`	String	Example: `README.md`

APIEntitiesCommitSequence

Property	Type	Description
`count`	Integer	Example: `1`

APIEntitiesCommitSignature

Property	Type	Description
`commit_source`	String	Example: `gitaly`
`signature`	Object	—
`signature_type`	String	Example: `PGP`

APIEntitiesCommitStats

Property	Type	Description
`additions`	Integer	Example: `1`
`deletions`	Integer	Example: `0`
`total`	Integer	Example: `1`

APIEntitiesCustomAttribute

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

APIEntitiesDiff

Property	Type	Description
`a_mode`	String	Example: `100755`
`b_mode`	String	Example: `100644`
`collapsed`	Boolean	—
`deleted_file`	Boolean	—
`diff`	String	Example: `@@ -71,6 +71,8 @@\n...`
`generated_file`	Boolean	—
`new_file`	Boolean	—
`new_path`	String	Example: `doc/update/5.4-to-6.0.md`
`old_path`	String	Example: `doc/update/5.4-to-6.0.md`
`renamed_file`	Boolean	—
`too_large`	Boolean	—

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`

APIEntitiesMergeRequestAuthor

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`
`bot`	Boolean	Example: `false`
`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`

APIEntitiesMergeRequestBasic

Property	Type	Description
`allow_collaboration`	Boolean	—
`allow_maintainer_to_push`	Boolean	—
`assignee`	APIEntitiesUserBasic	—
`assignees`	APIEntitiesUserBasic	—
`author`	APIEntitiesMergeRequestAuthor	—
`blocking_discussions_resolved`	Boolean	—
`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`
`discussion_locked`	Boolean	—
`downvotes`	Integer	—
`draft`	Boolean	—
`force_remove_source_branch`	Boolean	—
`has_conflicts`	Boolean	—
`id`	Integer (int64)	Example: `84`
`iid`	Integer	Example: `14`
`imported`	Boolean	—
`imported_from`	String	Example: `bitbucket`
`labels`	Array of strings	—
`merge_after`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`merge_commit_sha`	String	Example: `1234abcd`
`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	—
`prepared_at`	String (date-time)	Example: `2022-01-31T15:10:45.080Z`
`project_id`	Integer (int64)	Example: `4`
`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`
`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_notes_count`	Integer	—
`web_url`	String	Example: `https://gitlab.example.com/my-group/my-project/-/merge_requests/1`
`work_in_progress`	Boolean	—

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	—

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`

List all repository commits

Create a commit

Retrieve a commit

Cherry-pick a commit

List all commit comments

Create a comment on a commit

Retrieve a commit diff

List all merge requests associated with a commit

List all references a commit is pushed to

Revert a commit

Retrieve a commit sequence

Retrieve a commit signature

Schemas

APIEntitiesBasicRef

APIEntitiesCommit

APIEntitiesCommitDetail

APIEntitiesCommitNote

APIEntitiesCommitSequence

APIEntitiesCommitSignature

APIEntitiesCommitStats

APIEntitiesCustomAttribute

APIEntitiesDiff

APIEntitiesIssuableReferences

APIEntitiesIssuableTimeStats

APIEntitiesMergeRequestAuthor

APIEntitiesMergeRequestBasic

APIEntitiesMilestone

APIEntitiesTaskCompletionStatus

APIEntitiesUserBasic

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

Request partner program details

Request received

Error