Skip to content

Help

Commits API

List repository commits

Get a list of repository commits in a project.

GET /projects/:id/repository/commits
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project owned by the authenticated user
ref_name string no The name of a repository branch or tag or if not given the default branch
since string no Only commits after or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
until string no Only commits before or on this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "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
Attribute Type Required Description
id integer/string yes The ID or URL-encoded path of the project
branch string yes The name of a branch
commit_message string yes Commit message
actions[] array yes An array of action hashes to commit as a batch. See the next table for what attributes it can take.
author_email string no Specify the commit author's email address
author_name string no Specify the commit author's name
actions[] Attribute Type Required Description
action string yes The action to perform, create, delete, move, update
file_path string yes Full path to the file. Ex. lib/class.rb
previous_path string no Original full path to the file being moved. Ex. lib/class1.rb
content string no File content, required for all except delete. Optional for move
encoding string no text or base64. text is default. 
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"
    }
  ]
}
JSON
)
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --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
}

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:

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: 9koXpg98eAheJpvBs5tK" "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"
  ],
  "stats": {
    "additions": 15,
    "deletions": 10,
    "total": 25
  },
  "status": "running"
}

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:

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
branch string yes The name of the branch 
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --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"
  ]
}

Get the diff of a commit

Get the diff of a commit in a project.

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

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: 9koXpg98eAheJpvBs5tK" "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:

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: 9koXpg98eAheJpvBs5tK" "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
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 SHA or name of a repository branch or tag
note string yes The text of the comment
path string no The file path relative to the repository
line integer no The line number where the comment should be placed
line_type string no The line type. Takes new or old as arguments 
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" --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.

Get the status of a commit

Get the statuses of a commit in a project.

GET /projects/:id/repository/commits/:sha/statuses
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 SHA
ref string no The name of a repository branch or tag or, if not given, the default branch
stage string no Filter by build stage, e.g., test
name string no Filter by job name, e.g., bundler:audit
all boolean no Return all statuses, not only the latest ones 
curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "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-ce/builds/91",
      "finished_at" : null,
      "id" : 91,
      "ref" : "master"
   },
   {
      "started_at" : null,
      "name" : "flay",
      "allow_failure" : false,
      "status" : "pending",
      "created_at" : "2016-01-19T08:40:25.832Z",
      "target_url" : "https://gitlab.example.com/thedude/gitlab-ce/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
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 SHA
state string yes The state of the status. Can be one of the following: pending, running, success, failed, canceled
ref string no The ref (branch or tag) to which the status refers
name or context string no The label to differentiate this status from the status of other systems. Default value is default
target_url string no The target URL to associate with this status
description string no The short description of the status
coverage float no The total code coverage 
curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "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"
}