GitSwarm-EE 2017.2-1 Documentation

---

• Commits API
  • List repository commits
  • Create a commit with multiple files and actions
  • Get a single commit
  • Cherry pick a commit
  • Get the diff of a commit
  • Get the comments of a commit
  • Post comment to commit
  • Commit status
    • Get the status of a commit
    • Post the build status to a commit

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 of a project or NAMESPACE/PROJECT_NAME 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 in this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ
until	string	no	Only commits before or in this date will be returned in ISO 8601 format YYYY-MM-DDTHH:MM:SSZ

curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/5/repository/commits"

Example response:

[
  {
    "id": "ed899a2f4b50b4370feeea94676502b42383c746",
    "short_id": "ed899a2f4b5",
    "title": "Replace sanitize with escape once",
    "author_name": "Dmitriy Zaporozhets",
    "author_email": "[email protected]",
    "committer_name": "Administrator",
    "committer_email": "[email protected]",
    "created_at": "2012-09-20T11:50:22+03:00",
    "message": "Replace sanitize with escape once",
    "allow_failure": false
  },
  {
    "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
    "short_id": "6104942438c",
    "title": "Sanitize for network graph",
    "author_name": "randx",
    "author_email": "[email protected]",
    "committer_name": "Dmitriy",
    "committer_email": "[email protected]",
    "created_at": "2012-09-20T09:06:12+03:00",
    "message": "Sanitize for network graph",
    "allow_failure": false
  }
]

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 of a project or NAMESPACE/PROJECT_NAME
branch_name	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_name": "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/v3/projects/1/repository/commits

Example response:

{
  "id": "ed899a2f4b50b4370feeea94676502b42383c746",
  "short_id": "ed899a2f4b5",
  "title": "some commit message",
  "author_name": "Dmitriy Zaporozhets",
  "author_email": "[email protected]",
  "committer_name": "Dmitriy Zaporozhets",
  "committer_email": "[email protected]",
  "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 of a project or NAMESPACE/PROJECT_NAME 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/v3/projects/5/repository/commits/master

Example response:

{
  "id": "6104942438c14ec7bd21c6cd5bd995272b3faff6",
  "short_id": "6104942438c",
  "title": "Sanitize for network graph",
  "author_name": "randx",
  "author_email": "[email protected]",
  "committer_name": "Dmitriy",
  "committer_email": "[email protected]",
  "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 of a project or NAMESPACE/PROJECT_NAME 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/v3/projects/5/repository/commits/master/cherry_pick"

Example response:

{
  "id": "8b090c1b79a14f2bd9e8a738f717824ff53aebad",
  "short_id": "8b090c1b",
  "title": "Feature added",
  "author_name": "Dmitriy Zaporozhets",
  "author_email": "[email protected]",
  "created_at": "2016-12-12T20:10:39.000+01:00",
  "committer_name": "Administrator",
  "committer_email": "[email protected]",
  "message": "Feature added\n\nSigned-off-by: Dmitriy Zaporozhets <[email protected]>\n"
}

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 of a project or NAMESPACE/PROJECT_NAME 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/v3/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 of a project or NAMESPACE/PROJECT_NAME 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/v3/projects/5/repository/commits/master/comments"

Example response:

[
  {
    "note": "this code is really nice",
    "author": {
      "id": 11,
      "username": "admin",
      "email": "[email protected]",
      "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 of a project or NAMESPACE/PROJECT_NAME 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/v3/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 of a project or NAMESPACE/PROJECT_NAME 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/v3/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 of a project or NAMESPACE/PROJECT_NAME 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

curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/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",
   "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"
}