Merge branch 'commit_status' into 'master'

Implement Commit Status API

This is preliminary implementation of Commit Status API, pretty much compatible with GitHub.

1. The Commit Statuses are stored in separate table: ci_commit_status.
2. The POST inserts a new row.
3. To POST execute GitLab API `post :id/repository/commits/:sha/status`. This accepts dual authorization:
- Using authorized user
- Using ci-token to allow easy posting from CI Services
4. This adds predefined variable to GitLab CI build environment: CI_BUILD_STATUS_URL, allowing to easy post status from within build (ex. with code coverage or other metrics).
5. This adds statuses to commit's builds view.
6. The commit's status is calculated taking into account status of all builds and all posted statuses.
7. The commit statuses doesn't trigger notifications.
8. The commit status API introduces two new privileges: `read_commit_statuses` and `create_commit_status`.
9. We still miss a few tests and documentation updates for API and CI.

@dzaporozhets @sytses What do you think?




See merge request !1530

CHANGELOG

@@ -16,6 +16,7 @@ v 8.1.0 (unreleased)
   - Move CI charts to project graphs area
   - Fix cases where Markdown did not render links in activity feed (Stan Hu)
   - Add first and last to pagination (Zeger-Jan van de Weg)
+  - Added Commit Status API
   - Show CI status on commit page
   - Show CI status on Your projects page and Starred projects page
   - Remove "Continuous Integration" page from dashboard

app/models/ability.rb

@@ -135,6 +135,8 @@ class Ability
     def project_report_rules
       project_guest_rules + [
+        :create_commit_status,
+        :read_commit_statuses,
         :download_code,
         :fork_project,
         :create_project_snippet,

app/models/ci/build.rb

@@ -24,32 +24,19 @@
 #
 module Ci
-  class Build < ActiveRecord::Base
-    extend Ci::Model
-
+  class Build < CommitStatus
     LAZY_ATTRIBUTES = ['trace']
-    belongs_to :commit, class_name: 'Ci::Commit'
     belongs_to :runner, class_name: 'Ci::Runner'
     belongs_to :trigger_request, class_name: 'Ci::TriggerRequest'
-    belongs_to :user
     serialize :options
-    validates :commit, presence: true
-    validates :status, presence: true
     validates :coverage, numericality: true, allow_blank: true
     validates_presence_of :ref
-    scope :running, ->() { where(status: "running") }
-    scope :pending, ->() { where(status: "pending") }
-    scope :success, ->() { where(status: "success") }
-    scope :failed, ->() { where(status: "failed")  }
     scope :unstarted, ->() { where(runner_id: nil) }
-    scope :running_or_pending, ->() { where(status:[:running, :pending]) }
-    scope :latest, ->() { where(id: unscope(:select).select('max(id)').group(:name, :ref)).order(stage_idx: :asc) }
     scope :ignore_failures, ->() { where(allow_failure: false) }
-    scope :for_ref, ->(ref) { where(ref: ref) }
     scope :similar, ->(build) { where(ref: build.ref, tag: build.tag, trigger_request_id: build.trigger_request_id) }
     acts_as_taggable
@@ -74,13 +61,14 @@ module Ci
       def create_from(build)
         new_build = build.dup
-        new_build.status = :pending
+        new_build.status = 'pending'
         new_build.runner_id = nil
+        new_build.trigger_request_id = nil
         new_build.save
       end
       def retry(build)
-        new_build = Ci::Build.new(status: :pending)
+        new_build = Ci::Build.new(status: 'pending')
         new_build.ref = build.ref
         new_build.tag = build.tag
         new_build.options = build.options
@@ -98,28 +86,7 @@ module Ci
     end
     state_machine :status, initial: :pending do
-      event :run do
-        transition pending: :running
-      end
-
-      event :drop do
-        transition running: :failed
-      end
-
-      event :success do
-        transition running: :success
-      end
-
-      event :cancel do
-        transition [:pending, :running] => :canceled
-      end
-
-      after_transition pending: :running do |build, transition|
-        build.update_attributes started_at: Time.now
-      end
-
       after_transition any => [:success, :failed, :canceled] do |build, transition|
-        build.update_attributes finished_at: Time.now
         project = build.project
         if project.web_hooks?
@@ -136,19 +103,10 @@ module Ci
           build.update_coverage
         end
       end
-
-      state :pending, value: 'pending'
-      state :running, value: 'running'
-      state :failed, value: 'failed'
-      state :success, value: 'success'
-      state :canceled, value: 'canceled'
     end
-    delegate :sha, :short_sha, :project, :gl_project,
-      to: :commit, prefix: false
-
-    def before_sha
-      Gitlab::Git::BLANK_SHA
+    def ignored?
+      failed? && allow_failure?
     end
     def trace_html
@@ -156,22 +114,6 @@ module Ci
       html || ''
     end
-    def started?
-      !pending? && !canceled? && started_at
-    end
-
-    def active?
-      running? || pending?
-    end
-
-    def complete?
-      canceled? || success? || failed?
-    end
-
-    def ignored?
-      failed? && allow_failure?
-    end
-
     def timeout
       project.timeout
     end
@@ -180,14 +122,6 @@ module Ci
       yaml_variables + project_variables + trigger_variables
     end
-    def duration
-      if started_at && finished_at
-        finished_at - started_at
-      elsif started_at
-        Time.now - started_at
-      end
-    end
-
     def project
       commit.project
     end
@@ -278,6 +212,25 @@ module Ci
       "#{dir_to_trace}/#{id}.log"
     end
+    def target_url
+      Gitlab::Application.routes.url_helpers.
+        namespace_project_build_url(gl_project.namespace, gl_project, self)
+    end
+
+    def cancel_url
+      if active?
+        Gitlab::Application.routes.url_helpers.
+          cancel_namespace_project_build_path(gl_project.namespace, gl_project, self, return_to: request.original_url)
+      end
+    end
+
+    def retry_url
+      if commands.present?
+        Gitlab::Application.routes.url_helpers.
+          cancel_namespace_project_build_path(gl_project.namespace, gl_project, self, return_to: request.original_url)
+      end
+    end
+
     private
     def yaml_variables

app/models/ci/commit.rb

@@ -20,7 +20,8 @@ module Ci
     extend Ci::Model
     belongs_to :gl_project, class_name: '::Project', foreign_key: :gl_project_id
-    has_many :builds, dependent: :destroy, class_name: 'Ci::Build'
+    has_many :statuses, dependent: :destroy, class_name: 'CommitStatus'
+    has_many :builds, class_name: 'Ci::Build'
     has_many :trigger_requests, dependent: :destroy, class_name: 'Ci::TriggerRequest'
     validates_presence_of :sha
@@ -47,7 +48,7 @@ module Ci
     end
     def retry
-      builds_without_retry.each do |build|
+      latest_builds.each do |build|
         Ci::Build.retry(build)
       end
     end
@@ -81,12 +82,11 @@ module Ci
     end
     def stage
-      running_or_pending = builds_without_retry.running_or_pending
-      running_or_pending.limit(1).pluck(:stage).first
+      running_or_pending = statuses.latest.running_or_pending.ordered
+      running_or_pending.first.try(:stage)
     end
     def create_builds(ref, tag, user, trigger_request = nil)
-      return if skip_ci? && trigger_request.blank?
       return unless config_processor
       config_processor.stages.any? do |stage|
         CreateBuildsService.new.execute(self, stage, ref, tag, user, trigger_request).present?
@@ -94,7 +94,6 @@ module Ci
     end
     def create_next_builds(ref, tag, user, trigger_request)
-      return if skip_ci? && trigger_request.blank?
       return unless config_processor
       stages = builds.where(ref: ref, tag: tag, trigger_request: trigger_request).group_by(&:stage)
@@ -107,61 +106,60 @@ module Ci
     end
     def refs
-      builds.group(:ref).pluck(:ref)
+      statuses.order(:ref).pluck(:ref).uniq
     end
-    def last_ref
-      builds.latest.first.try(:ref)
+    def latest_statuses
+      @latest_statuses ||= statuses.latest.to_a
     end
-    def builds_without_retry
-      builds.latest
+    def latest_builds
+      @latest_builds ||= builds.latest.to_a
     end
-    def builds_without_retry_for_ref(ref)
-      builds.for_ref(ref).latest
+    def latest_builds_for_ref(ref)
+      latest_builds.select { |build| build.ref == ref }
     end
-    def retried_builds
-      @retried_builds ||= (builds.order(id: :desc) - builds_without_retry)
+    def retried
+      @retried ||= (statuses.order(id: :desc) - statuses.latest)
     end
     def status
-      if skip_ci?
-        return 'skipped'
-      elsif yaml_errors.present?
+      if yaml_errors.present?
         return 'failed'
-      elsif builds.none?
-        return 'skipped'
-      elsif success?
-        'success'
-      elsif pending?
-        'pending'
-      elsif running?
-        'running'
-      elsif canceled?
-        'canceled'
-      else
-        'failed'
+      end
+
+      @status ||= begin
+        latest = latest_statuses
+        latest.reject! { |status| status.try(&:allow_failure?) }
+
+        if latest.none?
+          'skipped'
+        elsif latest.all?(&:success?)
+          'success'
+        elsif latest.all?(&:pending?)
+          'pending'
+        elsif latest.any?(&:running?) || latest.any?(&:pending?)
+          'running'
+        elsif latest.all?(&:canceled?)
+          'canceled'
+        else
+          'failed'
+        end
       end
     end
     def pending?
-      builds_without_retry.all? do |build|
-        build.pending?
-      end
+      status == 'pending'
     end
     def running?
-      builds_without_retry.any? do |build|
-        build.running? || build.pending?
-      end
+      status == 'running'
     end
     def success?
-      builds_without_retry.all? do |build|
-        build.success? || build.ignored?
-      end
+      status == 'success'
     end
     def failed?
@@ -169,26 +167,21 @@ module Ci
     end
     def canceled?
-      builds_without_retry.all? do |build|
-        build.canceled?
-      end
+      status == 'canceled'
     end
     def duration
-      @duration ||= builds_without_retry.select(&:duration).sum(&:duration).to_i
-    end
-
-    def duration_for_ref(ref)
-      builds_without_retry_for_ref(ref).select(&:duration).sum(&:duration).to_i
+      duration_array = latest_statuses.map(&:duration).compact
+      duration_array.reduce(:+).to_i
     end
     def finished_at
-      @finished_at ||= builds.order('finished_at DESC').first.try(:finished_at)
+      @finished_at ||= statuses.order('finished_at DESC').first.try(:finished_at)
     end
     def coverage
       if project.coverage_enabled?
-        coverage_array = builds_without_retry.map(&:coverage).compact
+        coverage_array = latest_builds.map(&:coverage).compact
         if coverage_array.size >= 1
           '%.2f' % (coverage_array.reduce(:+) / coverage_array.size)
         end
@@ -196,7 +189,7 @@ module Ci
     end
     def matrix_for_ref?(ref)
-      builds_without_retry_for_ref(ref).pluck(:id).size > 1
+      latest_builds_for_ref(ref).size > 1
     end
     def config_processor
@@ -217,7 +210,6 @@ module Ci
     end
     def skip_ci?
-      return false if builds.any?
       git_commit_message =~ /(\[ci skip\])/ if git_commit_message
     end

app/models/commit.rb

@@ -184,4 +184,12 @@ class Commit
   def parents
     @parents ||= Commit.decorate(super, project)
   end
+
+  def ci_commit
+    project.ci_commit(sha)
+  end
+
+  def status
+    ci_commit.try(:status) || :not_found
+  end
 end

app/models/commit_status.rb

+class CommitStatus < ActiveRecord::Base
+  self.table_name = 'ci_builds'
+
+  belongs_to :commit, class_name: 'Ci::Commit'
+  belongs_to :user
+
+  validates :commit, presence: true
+  validates :status, inclusion: { in: %w(pending running failed success canceled) }
+
+  validates_presence_of :name
+
+  alias_attribute :author, :user
+
+  scope :running, -> { where(status: 'running') }
+  scope :pending, -> { where(status: 'pending') }
+  scope :success, -> { where(status: 'success') }
+  scope :failed, -> { where(status: 'failed')  }
+  scope :running_or_pending, -> { where(status:[:running, :pending]) }
+  scope :latest, -> { where(id: unscope(:select).select('max(id)').group(:name, :ref)) }
+  scope :ordered, -> { order(:ref, :stage_idx, :name) }
+  scope :for_ref, ->(ref) { where(ref: ref) }
+  scope :running_or_pending, -> { where(status: [:running, :pending]) }
+
+  state_machine :status, initial: :pending do
+    event :run do
+      transition pending: :running
+    end
+
+    event :drop do
+      transition running: :failed
+    end
+
+    event :success do
+      transition [:pending, :running] => :success
+    end
+
+    event :cancel do
+      transition [:pending, :running] => :canceled
+    end
+
+    after_transition pending: :running do |build, transition|
+      build.update_attributes started_at: Time.now
+    end
+
+    after_transition any => [:success, :failed, :canceled] do |build, transition|
+      build.update_attributes finished_at: Time.now
+    end
+
+    state :pending, value: 'pending'
+    state :running, value: 'running'
+    state :failed, value: 'failed'
+    state :success, value: 'success'
+    state :canceled, value: 'canceled'
+  end
+
+  delegate :sha, :short_sha, :gl_project,
+           to: :commit, prefix: false
+
+  # TODO: this should be removed with all references
+  def before_sha
+    Gitlab::Git::BLANK_SHA
+  end
+
+  def started?
+    !pending? && !canceled? && started_at
+  end
+
+  def active?
+    running? || pending?
+  end
+
+  def complete?
+    canceled? || success? || failed?
+  end
+
+  def duration
+    if started_at && finished_at
+      finished_at - started_at
+    elsif started_at
+      Time.now - started_at
+    end
+  end
+
+  def cancel_url
+    nil
+  end
+
+  def retry_url
+    nil
+  end
+end

app/models/generic_commit_status.rb

+class GenericCommitStatus < CommitStatus
+  before_validation :set_default_values
+
+  # GitHub compatible API
+  alias_attribute :context, :name
+
+  def set_default_values
+    self.context ||= 'default'
+    self.stage ||= 'external'
+  end
+
+  def tags
+    [:external]
+  end
+end

app/models/project_services/ci/hip_chat_service.rb

@@ -49,7 +49,7 @@ module Ci
       commit = build.commit
       return unless commit
-      return unless commit.builds_without_retry.include? build
+      return unless commit.latest_builds.include? build
       case commit.status.to_sym
       when :failed

app/models/project_services/ci/mail_service.rb

@@ -48,7 +48,7 @@ module Ci
       # it doesn't make sense to send emails for retried builds
       commit = build.commit
       return unless commit
-      return unless commit.builds_without_retry.include?(build)
+      return unless commit.latest_builds.include?(build)
       case build.status.to_sym
       when :failed

app/models/project_services/ci/slack_message.rb

@@ -23,7 +23,7 @@ module Ci
     def attachments
       fields = []
-      commit.builds_without_retry.each do |build|
+      commit.latest_builds.each do |build|
         next if build.allow_failure?
         next unless build.failed?
         fields << {

app/models/project_services/ci/slack_service.rb

@@ -48,7 +48,7 @@ module Ci
       commit = build.commit
       return unless commit
-      return unless commit.builds_without_retry.include?(build)
+      return unless commit.latest_builds.include?(build)
       case commit.status.to_sym
       when :failed

app/services/ci/create_commit_service.rb

@@ -17,8 +17,10 @@ module Ci
       tag = origin_ref.start_with?('refs/tags/')
       commit = project.gl_project.ensure_ci_commit(sha)
-      commit.update_committed!
-      commit.create_builds(ref, tag, user)
+      unless commit.skip_ci?
+        commit.update_committed!
+        commit.create_builds(ref, tag, user)
+      end
       commit
     end

app/views/projects/builds/_build.html.haml

-- gl_project = build.project.gl_project
-%tr.build
-  %td.status
-    = ci_status_with_icon(build.status)
-
-  %td.build-link
-    = link_to namespace_project_build_path(gl_project.namespace, gl_project, build) do
-      %strong Build ##{build.id}
-
-  - if defined?(ref)
-    %td
-      = build.ref
-
-  %td
-    = build.stage
-
-  %td
-    = build.name
-    .pull-right
-      - if build.tags.any?
-        - build.tag_list.each do |tag|
-          %span.label.label-primary
-            = tag
-      - if build.trigger_request
-        %span.label.label-info triggered
-      - if build.allow_failure
-        %span.label.label-danger allowed to fail
-
-  %td.duration
-    - if build.duration
-      #{duration_in_words(build.finished_at, build.started_at)}
-
-  %td.timestamp
-    - if build.finished_at
-      %span #{time_ago_in_words build.finished_at} ago
-
-  - if build.project.coverage_enabled?
-    %td.coverage
-      - if build.coverage
-        #{build.coverage}%
-
-  %td
-    - if defined?(controls) && current_user && can?(current_user, :manage_builds, gl_project)
-      .pull-right
-        - if build.active?
-          = link_to cancel_namespace_project_build_path(gl_project.namespace, gl_project, build, return_to: request.original_url), title: 'Cancel build' do
-            %i.fa.fa-remove.cred
-        - elsif build.commands.present?
-          = link_to retry_namespace_project_build_path(gl_project.namespace, gl_project, build, return_to: request.original_url), method: :post, title: 'Retry build' do
-            %i.fa.fa-repeat

app/views/projects/builds/show.html.haml

@@ -9,7 +9,7 @@
   #up-build-trace
   - if @commit.matrix_for_ref?(@build.ref)
     %ul.center-top-menu.build-top-menu
-      - @commit.builds_without_retry_for_ref(@build.ref).each do |build|
+      - @commit.latest_builds_for_ref(@build.ref).each do |build|
         %li{class: ('active' if build == @build) }
           = link_to namespace_project_build_path(@project.namespace, @project, build) do
             = ci_icon_for_status(build.status)
@@ -20,7 +20,7 @@
                 = build.id
-      - unless @commit.builds_without_retry_for_ref(@build.ref).include?(@build)
+      - unless @commit.latest_builds_for_ref(@build.ref).include?(@build)
         %li.active
           %a
             Build ##{@build.id}

app/views/projects/commit/ci.html.haml

@@ -20,30 +20,31 @@
   .bs-callout.bs-callout-warning
     \.gitlab-ci.yml not found in this commit
-- @ci_commit.refs.each do |ref|
+.gray-content-block.second-block
+  Latest builds
+  - if @ci_commit.duration > 0
+    %small.pull-right
+      %i.fa.fa-time
+      #{time_interval_in_words @ci_commit.duration}
+
+%table.table.builds
+  %thead
+    %tr
+      %th Status
+      %th Build ID
+      %th Ref
+      %th Stage
+      %th Name
+      %th Duration
+      %th Finished at
+      - if @ci_project && @ci_project.coverage_enabled?
+        %th Coverage
+      %th
+  - @ci_commit.refs.each do |ref|
+    = render partial: "projects/commit_statuses/commit_status", collection: @ci_commit.statuses.for_ref(ref).latest.ordered, coverage: @ci_project.try(:coverage_enabled?), controls: true
+
+- if @ci_commit.retried.any?
   .gray-content-block.second-block
-    Builds for #{ref}
-    - if @ci_commit.duration_for_ref(ref) > 0
-      %small.pull-right
-        %i.fa.fa-time
-        #{time_interval_in_words @ci_commit.duration_for_ref(ref)}
-
-  %table.table.builds
-    %thead
-      %tr
-        %th Status
-        %th Build ID
-        %th Stage
-        %th Name
-        %th Duration
-        %th Finished at
-        - if @ci_project && @ci_project.coverage_enabled?
-          %th Coverage
-        %th
-    = render partial: "projects/builds/build", collection: @ci_commit.builds_without_retry.for_ref(ref), controls: true
-
-- if @ci_commit.retried_builds.any?
-  %h3
     Retried builds
   %table.table.builds
@@ -59,4 +60,4 @@
         - if @ci_project && @ci_project.coverage_enabled?
           %th Coverage
         %th
-    = render partial: "projects/builds/build", collection: @ci_commit.retried_builds, ref: true
+    = render partial: "projects/commit_statuses/commit_status", collection: @ci_commit.retried, coverage: @ci_project.try(:coverage_enabled?)

app/views/projects/commit_statuses/_commit_status.html.haml

+%tr.commit_status
+  %td.status
+    = ci_status_with_icon(commit_status.status)
+
+  %td.commit_status-link
+    - if commit_status.target_url
+      = link_to commit_status.target_url do
+        %strong Build ##{commit_status.id}
+    - else
+      %strong Build ##{commit_status.id}
+
+  %td
+    = commit_status.ref
+
+  %td
+    = commit_status.stage
+
+  %td
+    = commit_status.name
+    .pull-right
+      - if commit_status.tags.any?
+        - commit_status.tags.each do |tag|
+          %span.label.label-primary
+            = tag
+      - if commit_status.try(:trigger_request)
+        %span.label.label-info triggered
+      - if commit_status.try(:allow_failure)
+        %span.label.label-danger allowed to fail
+
+  %td.duration
+    - if commit_status.duration
+      #{duration_in_words(commit_status.finished_at, commit_status.started_at)}
+
+  %td.timestamp
+    - if commit_status.finished_at
+      %span #{time_ago_in_words commit_status.finished_at} ago
+
+  - if defined?(coverage) && coverage
+    %td.coverage
+      - if commit_status.try(:coverage)
+        #{commit_status.coverage}%
+
+  %td
+    - if defined?(controls) && controls && current_user && can?(current_user, :manage_builds, gl_project)
+      .pull-right
+        - if commit_status.cancel_url
+          = link_to commit_status.cancel_url, title: 'Cancel' do
+            %i.fa.fa-remove.cred
+        - elsif commit_status.retry_url
+          = link_to commit_status.retry_url, method: :post, title: 'Retry' do
+            %i.fa.fa-repeat

db/migrate/20151008123042_add_type_and_description_to_builds.rb

+class AddTypeAndDescriptionToBuilds < ActiveRecord::Migration
+  def change
+    add_column :ci_builds, :type, :string
+    add_column :ci_builds, :target_url, :string
+    add_column :ci_builds, :description, :string
+    add_index :ci_builds, [:commit_id, :type, :ref]
+    add_index :ci_builds, [:commit_id, :type, :name, :ref]
+  end
+end

db/migrate/20151008130321_migrate_name_to_description_for_builds.rb

+class MigrateNameToDescriptionForBuilds < ActiveRecord::Migration
+  def change
+    execute("UPDATE ci_builds SET type='Ci::Build' WHERE type IS NULL")
+  end
+end

db/schema.rb

@@ -11,7 +11,7 @@
 #
 # It's strongly recommended that you check this file into your version control system.
-ActiveRecord::Schema.define(version: 20151007120511) do
+ActiveRecord::Schema.define(version: 20151008130321) do
   # These are extensions that must be enabled in order to support this database
   enable_extension "plpgsql"
@@ -103,9 +103,14 @@ ActiveRecord::Schema.define(version: 20151007120511) do
     t.boolean  "tag"
     t.string   "ref"
     t.integer  "user_id"
+    t.string   "type"
+    t.string   "target_url"
+    t.string   "description"
   end
   add_index "ci_builds", ["commit_id", "stage_idx", "created_at"], name: "index_ci_builds_on_commit_id_and_stage_idx_and_created_at", using: :btree
+  add_index "ci_builds", ["commit_id", "type", "name", "ref"], name: "index_ci_builds_on_commit_id_and_type_and_name_and_ref", using: :btree
+  add_index "ci_builds", ["commit_id", "type", "ref"], name: "index_ci_builds_on_commit_id_and_type_and_ref", using: :btree
   add_index "ci_builds", ["commit_id"], name: "index_ci_builds_on_commit_id", using: :btree
   add_index "ci_builds", ["project_id", "commit_id"], name: "index_ci_builds_on_project_id_and_commit_id", using: :btree
   add_index "ci_builds", ["project_id"], name: "index_ci_builds_on_project_id", using: :btree

doc/api/commits.md

@@ -62,7 +62,8 @@ Parameters:
   "authored_date": "2012-09-20T09:06:12+03:00",
   "parent_ids": [
     "ae1d9fb46aa2b07ee9836d49862ec4e2c46fbbba"
-  ]
+  ],
+  "status": "running"
 }
 ```
@@ -156,3 +157,84 @@ 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.
+
+```
+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"
+  }
+}
+```