GitSwarm 2016.3-2 Documentation

Commits API

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	yes	The ID of a project
`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 -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.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]",
    "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]",
    "created_at": "2012-09-20T09:06:12+03:00",
    "message": "Sanitize for network graph",
    "allow_failure": false
  }
]

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	yes	The ID of a project
`sha`	string	yes	The commit hash or name of a repository branch or tag

curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.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]",
  "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"
  ],
  "status": "running"
}

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	yes	The ID of a project
`sha`	string	yes	The commit hash or name of a repository branch or tag

curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.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 assets:precompile 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	yes	The ID of a project
`sha`	string	yes	The commit hash or name of a repository branch or tag

curl -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.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	yes	The ID of a project
`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 -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" -F "note=Nice picture man\!" -F "path=dudeism.md" -F "line=11" -F "line_type=new" https://gitswarm.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments

Example response:

{
   "author" : {
      "web_url" : "https://gitswarm.example.com/u/thedude",
      "avatar_url" : "https://gitswarm.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 GitSwarm 2016.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	yes	The ID of a project
`sha`	string	yes	The commit SHA
`ref_name`	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 -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.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://gitswarm.example.com/u/thedude",
         "avatar_url" : "https://gitswarm.example.com/uploads/user/avatar/28/The-Big-Lebowski-400-400.png",
         "id" : 28,
         "name" : "Jeff Lebowski"
      },
      "description" : null,
      "sha" : "18f3e63d05582537db6d183d9d557be09e1f90c8",
      "target_url" : "https://gitswarm.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://gitswarm.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://gitswarm.example.com/u/thedude",
         "state" : "active",
         "avatar_url" : "https://gitswarm.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	yes	The ID of a project
`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 -X POST -H "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitswarm.example.com/api/v3/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"

Example response:

{
   "author" : {
      "web_url" : "https://gitswarm.example.com/u/thedude",
      "name" : "Jeff Lebowski",
      "avatar_url" : "https://gitswarm.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"
}