GET /projects/:id/repository/commits
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
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
untilstringnoOnly commits before or on this date are returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
pathstringnoThe file path
authorstringnoSearch commits by commit author.
allbooleannoRetrieve every commit from the repository
with_statsbooleannoStats about each commit are added to the response
first_parentbooleannoFollow 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.
trailersbooleannoParse and include Git trailers for every commitcurl --header "PRIVATE-TOKEN: <your_access_token>" "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"
"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",
"parent_ids": [
"ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
"web_url": "https://gitlab.example.com/janedoe/gitlab-foss/-/commit/ed899a2f4b50b4370feeea94676502b42383c746"
Create a commit with multiple files and actions
Create a commit by posting a JSON payload
POST /projects/:id/repository/commits
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
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
start_branchstringnoName of the branch to start the new branch from
start_shastringnoSHA of the commit to start the new branch from
start_projectinteger/stringnoThe project ID or URL-encoded path of the project to start the new branch from. Defaults to the value of id.
actions[]arrayyesAn array of action hashes to commit as a batch. See the next table for what attributes it can take.
author_emailstringnoSpecify the commit author’s email address
author_namestringnoSpecify the commit author’s name
statsbooleannoInclude commit stats. Default is true
forcebooleannoWhen true overwrites the target branch with a new commit based on the start_branch or start_sha
actions[] AttributeTypeRequiredDescription
actionstringyesThe action to perform: create, delete, move, update, or chmod.
file_pathstringyesFull path to the file. For example: lib/class.rb.
previous_pathstringnoOriginal full path to the file being moved. For example lib/class1.rb. Only considered for move action.
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.
encodingstringno
text or base64. text is default.
last_commit_idstringnoLast known file commit ID. Only considered in update, move, and delete actions.
execute_filemodebooleannoWhen true/false enables/disables the execute flag on the file. Only considered for chmod action.PAYLOAD=$(cat << 'JSON'
"branch": "master",
"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
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --header "Content-Type: application/json" \
--data "$PAYLOAD" "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=master" \
--form "commit_message=some commit message" \
--form "start_branch=master" \
--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>" \
"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.
Parameters:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
sha | string | yes | The commit hash or name of a repository branch or tag |
stats | boolean | no | Include commit stats. Default is true |
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": "master",
"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 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:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
sha | string | yes | The commit hash |
type | string | no | The scope of commits. Possible values branch, tag, all. Default is all. |
Example response:
Cherry-picks a commit to a given branch.
Parameters:
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:
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:
In the event of a failure, an error displays that is identical to a failure without
dry run.
Reverts a commit in a given branch.
Parameters:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project
| sha | string | yes | Commit SHA to revert |
branch | string | yes | Target branch name |
dry_run | boolean | no | Does not commit any changes. Default is false. Introduced in GitLab 13.3 |
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:
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:
In the event of a failure, an error displays that is identical to a failure without
dry run.
Get the diff of a commit in a project.
Parameters:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
sha | string | yes | The commit hash or name of a repository branch or tag |
Example response:
Get the comments of a commit in a project.
Parameters:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
sha | string | yes | The commit hash or name of a repository branch or tag |
Example response:
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
cases below is valid:
In any of the above 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/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit SHA or name of a repository branch or tag
notestringyesThe text of the comment
pathstringnoThe file path relative to the repository
lineintegernoThe line number where the comment should be placed
line_typestringnoThe line type. Takes new or old as argumentscurl --request POST --header "PRIVATE-TOKEN: <your_access_token>" \
--form "note=Nice picture\!" --form "path=README.md" --form "line=11" --form "line_type=new" \
"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 the discussions of a commit
Get the discussions of a commit in a project.
Parameters:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
sha | string | yes | The commit hash or name of a repository branch or tag |
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": {}
This is the commit status API for use with GitLab.
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/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit SHA
refstringnoThe name of a repository branch or tag or, if not given, the default branch
stagestringnoFilter by build stage, for example, test
namestringnoFilter by job name, for example, bundler:audit
allbooleannoReturn all statuses, not only the latest onescurl --header "PRIVATE-TOKEN: <your_access_token>" "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" : "master"
"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" : "master",
"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 the pipeline status of a commit
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.
POST /projects/:id/statuses/:sha
AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit SHA
statestringyesThe state of the status. Can be one of the following: pending, running, success, failed, canceled
refstringnoThe ref (branch or tag) to which the status refers
name or context
stringnoThe label to differentiate this status from the status of other systems. Default value is default
target_urlstringnoThe target URL to associate with this status
descriptionstringnoThe short description of the status
coveragefloatnoThe total code coverage
pipeline_idintegernoThe ID of the pipeline to set status. Use in case of several pipeline on same SHA.curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "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/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit SHAcurl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/af5b13261899fb2c0db30abdd0af8b07cb44fdc5/merge_requests"
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":"master",
"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 GPG signature of a commit
Get the GPG 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:
| Attribute | Type | Required | Description |
|---|
id | integer/string | yes | The ID or URL-encoded path of the project owned by the authenticated user |
sha | string | yes | The commit hash or name of a repository branch or tag |
curl --header "PRIVATE-TOKEN: <your_access_token>" "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 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:
