Add Commit Status documentation

1 files changed, 82 insertions, 0 deletions

diff --git a/doc/api/commits.md b/doc/api/commits.md
index b22d040bf0d..78144dd42ef 100644
--- a/doc/api/commits.md
+++ b/doc/api/commits.md
@@ -157,3 +157,85 @@ Parameters:
   "line_type": "new"
 }
 ```
+
+## Get the status of a commit
+
+Get the statuses of a commit in a project.
+
+```
+GET /projects/:id/repository/commits/:sha/statuses
+```
+
+Parameters:
+
+- `id` (required) - The ID of a project
+- `sha` (required) - The commit SHA
+- `ref` (optional) - Filter by ref name, it can be branch or tag
+- `stage` (optional) - Filter by stage
+- `name` (optional) - Filer by status name, eg. jenkins
+- `all` (optional) - The flag to return all statuses, not only latest ones
+
+```json
+[
+  {
+    "id": 13,
+    "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27",
+    "ref": "test",
+    "status": "success",
+    "name": "ci/jenkins",
+    "target_url": "http://jenkins/project/url",
+    "description": "Jenkins success",
+    "created_at": "2015-10-12T09:47:16.250Z",
+    "started_at": "2015-10-12T09:47:16.250Z"",
+    "finished_at": "2015-10-12T09:47:16.262Z",
+    "author": {
+      "id": 1,
+      "username": "admin",
+      "email": "admin@local.host",
+      "name": "Administrator",
+      "blocked": false,
+      "created_at": "2012-04-29T08:46:00Z"
+    }
+  }
+]
+```
+
+## Post the status to commit
+
+Adds or updates a status of a commit.
+Optionally you can post comments on a specific line of a commit. Therefor both `path`, `line_new` and `line_old` are required.
+
+```
+POST /projects/:id/statuses/:sha
+```
+
+- `id` (required) - The ID of a project
+- `sha` (required) - The commit SHA
+- `state` (required) - The state of the status. Can be: pending, running, success, failed, canceled
+- `ref` (optional) - The ref (branch or tag) to which the status refers
+- `name` or `context` (optional) - The label to differentiate this status from the status of other systems. Default: "default"
+- `target_url` (optional) - The target URL to associate with this status
+- `description` (optional) - The short description of the status
+
+```json
+{
+  "id": 13,
+  "sha": "b0b3a907f41409829b307a28b82fdbd552ee5a27",
+  "ref": "test",
+  "status": "success",
+  "name": "ci/jenkins",
+  "target_url": "http://jenkins/project/url",
+  "description": "Jenkins success",
+  "created_at": "2015-10-12T09:47:16.250Z",
+  "started_at": "2015-10-12T09:47:16.250Z"",
+  "finished_at": "2015-10-12T09:47:16.262Z",
+  "author": {
+    "id": 1,
+    "username": "admin",
+    "email": "admin@local.host",
+    "name": "Administrator",
+    "blocked": false,
+    "created_at": "2012-04-29T08:46:00Z"
+  }
+}
+```