Commits API

List repository commits

Get a list of repository commits in a project.

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 will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
untilstringnoOnly commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
pathstringnoThe file path
allbooleannoRetrieve every commit from the repository
with_statsbooleannoStats about each commit will be added to the response
first_parentbooleannoFollow only the first parent commit upon seeing a merge commit
curl --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": "Dmitriy Zaporozhets",
    "author_email": "dzaporozhets@sphereconsultinginc.com",
    "authored_date": "2012-09-20T11:50:22+03:00",
    "committer_name": "Administrator",
    "committer_email": "admin@example.com",
    "committed_date": "2012-09-20T11:50:22+03:00",
    "created_at": "2012-09-20T11:50:22+03:00",
    "message": "Replace sanitize with escape once",
    "parent_ids": [
      "6104942438c14ec7bd21c6cd5bd995272b3faff6"
    ]
  },
  {
    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
    "short_id": "6104942438c",
    "title": "Sanitize for network graph",
    "author_name": "randx",
    "author_email": "dmitriy.zaporozhets@gmail.com",
    "committer_name": "Dmitriy",
    "committer_email": "dmitriy.zaporozhets@gmail.com",
    "created_at": "2012-09-20T09:06:12+03:00",
    "message": "Sanitize for network graph",
    "parent_ids": [
      "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
    ]
  }
]

Create a commit with multiple files and actions

Introduced in GitLab 8.13.

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, chmod
file_pathstringyesFull path to the file. Ex. lib/class.rb
previous_pathstringnoOriginal full path to the file being moved. Ex. 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 will preserve the existing file content, and any other value of content will overwrite the file content.
encodingstringnotext or base64. text is default.
last_commit_idstringnoLast known file commit id. Will be 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
    }
  ]
}
JSON
)
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": "Dmitriy Zaporozhets",
  "author_email": "dzaporozhets@sphereconsultinginc.com",
  "committer_name": "Dmitriy Zaporozhets",
  "committer_email": "dzaporozhets@sphereconsultinginc.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
}

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.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit hash or name of a repository branch or tag
statsbooleannoInclude commit stats. Default is true
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master

Example response:

{
  "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
  "short_id": "6104942438c",
  "title": "Sanitize for network graph",
  "author_name": "randx",
  "author_email": "dmitriy.zaporozhets@gmail.com",
  "committer_name": "Dmitriy",
  "committer_email": "dmitriy.zaporozhets@gmail.com",
  "created_at": "2012-09-20T09:06:12+03:00",
  "message": "Sanitize for network graph",
  "committed_date": "2012-09-20T09:06:12+03:00",
  "authored_date": "2012-09-20T09:06:12+03:00",
  "parent_ids": [
    "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
  ],
  "last_pipeline" : {
    "id": 8,
    "ref": "master",
    "sha": "2dc6aa325a317eda67812f05600bdf0fcdc70ab0",
    "status": "created"
  },
  "stats": {
    "additions": 15,
    "deletions": 10,
    "total": 25
  },
  "status": "running"
}

Get references a commit is pushed to

Introduced in GitLab 10.6

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/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit hash
typestringnoThe scope of commits. Possible values branch, tag, all. Default is all.
curl --header "PRIVATE-TOKEN: <your_access_token>" "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"}
 ]

Cherry pick a commit

Introduced in GitLab 8.15.

Cherry picks a commit to a given branch.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit hash
branchstringyesThe name of the branch
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/cherry_pick"

Example response:

{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "title": "Feature added",
  "author_name": "Dmitriy Zaporozhets",
  "author_email": "dmitriy.zaporozhets@gmail.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: Dmitriy Zaporozhets <dmitriy.zaporozhets@gmail.com>\n",
  "parent_ids": [
    "a738f717824ff53aebad8b090c1b79a14f2bd9e8"
  ]
}

In the event of a failed cherry-pick, the response will provide 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.

Revert a commit

Introduced in GitLab 11.5.

Reverts a commit in a given branch.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project
shastringyesCommit SHA to revert
branchstringyesTarget branch name
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "branch=master" "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"
}

In the event of a failed revert, the response will provide 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.

Get the diff of a commit

Get the diff of a commit in a project.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit hash or name of a repository branch or tag
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/diff"

Example response:

[
  {
    "diff": "--- a/doc/update/5.4-to-6.0.md\n+++ b/doc/update/5.4-to-6.0.md\n@@ -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 the comments of a commit

Get the comments of a commit in a project.

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

Parameters:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe commit hash or name of a repository branch or tag
curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/5/repository/commits/master/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.

In order 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 will be added at the end of the last commit if at least one of the cases below 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 above cases, the response of line, line_type and path is set to null.

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 arguments
curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" --form "note=Nice picture man\!" --form "path=dudeism.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/thedude",
      "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
      "username" : "thedude",
      "state" : "active",
      "name" : "Jeff Lebowski",
      "id" : 28
   },
   "created_at" : "2016-01-19T09:44:55.600Z",
   "line_type" : "new",
   "path" : "dudeism.md",
   "line" : 11,
   "note" : "Nice picture man!"
}

Commit status

Since GitLab 8.1, this is the new commit status API.

List the statuses of a commit

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, e.g., test
namestringnoFilter by job name, e.g., bundler:audit
allbooleannoReturn all statuses, not only the latest ones
curl --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" : "thedude",
         "state" : "active",
         "web_url" : "https://gitlab.example.com/thedude",
         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
         "id" : 28,
         "name" : "Jeff Lebowski"
      },
      "description" : null,
      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
      "target_url" : "https://gitlab.example.com/thedude/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/thedude/gitlab-foss/builds/90",
      "id" : 90,
      "finished_at" : null,
      "ref" : "master",
      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
      "author" : {
         "id" : 28,
         "name" : "Jeff Lebowski",
         "username" : "thedude",
         "web_url" : "https://gitlab.example.com/thedude",
         "state" : "active",
         "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png"
      },
      "description" : null
   },

   ...
]

Post the build status to a commit

Adds or updates a build status of a commit.

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 contextstringnoThe 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/thedude",
      "name" : "Jeff Lebowski",
      "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
      "username" : "thedude",
      "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

Introduced in GitLab 10.7.

Get a list of Merge Requests related to the specified 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 SHA
curl --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/thedude",
        "name" : "Jeff Lebowski",
        "avatar_url" : "https://gitlab.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
        "username" : "thedude",
        "state" : "active",
        "id" : 28
      },
      "assignee":null,
      "source_project_id":35,
      "target_project_id":35,
      "labels":[ ],
      "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":"http://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:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the project owned by the authenticated user
shastringyesThe 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 signed:

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

Example response if commit is unsigned:

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