GitSwarm-EE 2017.1-1 Documentation

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://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": "dzaporozhets@sphereconsultinginc.com",
    "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": "dmitriy.zaporozhets@gmail.com",
    "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 GitSwarm 2017.1.

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://gitswarm.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": "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 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://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": "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"
}

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://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/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://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": "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:

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://gitswarm.example.com/api/v3/projects/17/repository/commits/18f3e63d05582537db6d183d9d557be09e1f90c8/comments

Example response:

{
   "author" : {
      "web_url" : "https://gitswarm.example.com/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/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://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/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/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/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://gitswarm.example.com/api/v3/projects/17/statuses/18f3e63d05582537db6d183d9d557be09e1f90c8?state=success"

Example response:

{
   "author" : {
      "web_url" : "https://gitswarm.example.com/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"
}