Introduce a commit status API

Reports:

• feedback issue http://feedback.gitlab.com/forums/176466-general/suggestions/3923065-status-api-for-continuous-integration
• Status in commit index http://feedback.gitlab.com/forums/176466-general/suggestions/5608385-show-build-status-in-commit-index
• One major customer in customer electronics asked for this

We should allow external programs to submit a status of a commit. This should be used for GitLab CI and other external testing tools.

1. It should allow multiple programs to submit a status
2. It should allow the overwriting of a previous status (pending => failed => green)
3. States are: pending, success, error, or failure
4. It should be shown everywhere the commit is shown (MR, commit show, commit index, branch overview)
5. GitLab CI should use the same interface (no more getting a picture)

See GitHub post https://github.com/blog/1227-commit-status-api and docs https://developer.github.com/v3/repos/statuses/

And Stash post https://developer.atlassian.com/stash/docs/latest/how-tos/updating-build-status-for-commits.html

Third party CI service (CodeShip) are also asking for this.

Milestone changed to 8.1

Added promised label

/cc @dzaporozhets @ayufan @JobV

I see this as 2 stages:

1. we make UI concept on how commit status used/displayed (MR, commit show, commit index, branch overview)
2. Based on UI we define commit attributes we need and build API to allow external CI set it

I will propose concept for 1 and then delegate 2 to developer

Reassigned to @dzaporozhets

Thanks for looking into this @dzaporozhets

Integrating CI in GitLab will interest with this issue too - #2594 (closed)

I think the best way to do it is re-use models we already have and used by internal CI:

Commit

• sha
• branch/tag name
• project id
• external_url (point to CI page with commit)

Build

• status (success, failed, etc)
• commit_id
• name (optional)

We can unify this in one api call like:

POST /ci/api/status 

{
  sha: "ad321fas",           # Commit sha
  ref: "refs/heads/master"   # Branch or tag name
  name: "spec"               # Name of status
  project_id: 123,           # Project
  external_url: "http://jenkins.example.com/builds/123"
  status: "success"
}

This information will be enough to create Commit and Build objects.

It would be nice to allow to include custom message that would be shown on merge request page. That message could include, ex.: coverage information.

@ayufan yes. We can add it to commit or build model in our database

Comparing: GitLab | GitHub | Stash

  sha: "ad321fas",          | in url |  in url
  ref: "refs/heads/master"  | not included | not included
  name: "spec"              | context | name
  project_id: 123,         | in url | in url
  external_url: "URL"      | target_url | url
  status: "success"        | state | state

1. I think we should rename status to state.
2. I think we should add a description as @ayufan suggested and GitHub and Stash have.
3. I'm not sure if we should include ref.

We should exclude ref as a requirement in POST, as it would just make it harder to work with our API.

If we do the two other things @sytses has suggested, this makes it very easy to work with our API for existing services. They'll only have to change the root url and authentication.

+1

The problem with not having ref is that commit sha tested on master is not the same as commit sha tested on topic/feature.

We should have it, maybe optional.

Lets try to make it without ref. But we need to make changes on GitLab CI side. Now ref is part of routing and you can have same commit with different builds on different branches.

Reassigned to @ayufan

Final design:

The :id/repository/commits/:sha/status accepts POST with:

      #   id (required) - The ID of a project
      #   sha (required) - The commit hash
      #   ref (optional) - The ref
      #   state (required) - The state of the status. Can be: pending, running, success, error or failure
      #   target_url (optional) - The target URL to associate with this status
      #   description (optional) - A short description of the status
      #   context (optional) - A string label to differentiate this status from the status of other systems. Default: "default"

MR https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/1530

@ayufan Why instead :id/repository/commits/:sha/status of :owner/:repo/statuses/:sha? That seems easier for people using Jenkins to me.

Why do we have the ref? @dzaporozhets suggested to not have it.

/cc @dzaporozhets

context (optional) - A string label to differentiate this status from the status of other systems. Default: "default"

@sytses So in theory I could run two different build systems in parallel and I get both status with this api? i.e. gitlab ci and codeclimate

@sytses

• The ref is optional. When you build your project you run tests against specific ref.
• The context is also optional and @haynes described it nicely. We can have multiple services posting status.

@haynes Correct, GitLab will play nice with other systems (Jenkins)

@ayufan The ref can be a branch name or something? What does it mean if you test against that instead of the commit itself?

@ayufan Can you answer my first question? Can we use :owner/:repo/statuses/:sha as endpoint?

@sytse

The ref can be a branch name or something?

This ref is branch or tag name.

What does it mean if you test against that instead of the commit itself?

Ref allows the service to be more specific against which ref it was testing the :sha. We also use :ref tracking in GitLab CI, because in our builds we often have different pipelines for tags and branches, ie. omnibus package.

Can we use :owner/:repo/statuses/:sha as endpoint?

I don't see any objections to have: projects/:id/statuses/:sha

Where :id can be numeric ID of project or :namespace/:project.

@ayufan if we pass the tag to the runner it makes sense to store it, thanks

@ayufan if the :id can be :namespace/:project I'm fine with it, thanks.

The API is merged.

Status changed to closed

@ayufan awesome

@ayufan Did you contact the creator of the Jenkins plugin?

Status changed to reopened

@sytses https://github.com/DABSquared/gitlab-plugin/issues/111#issuecomment-148442906

I've also opened a pull request on another Jenkins plugin https://github.com/timols/jenkins-gitlab-merge-request-builder-plugin/pull/146

Thanks everyone!

Status changed to closed

mentioned in issue #13595 (moved)

marked this issue as related to #13227 (moved)