Merge branch 'ci/api-builds' into 'master'

Add builds API

References #4264

See merge request !2207

CHANGELOG

@@ -49,6 +49,7 @@ v 8.4.0 (unreleased)
   - Allow subsequent validations in CI Linter
   - Show referenced MRs & Issues only when the current viewer can access them
   - Fix Encoding::CompatibilityError bug when markdown content has some complex URL (Jason Lee)
+  - Add API support for managing builds of a project
   - Add API support for managing build variables of project
   - Allow broadcast messages to be edited
   - Autosize Markdown textareas

app/models/commit_status.rb

@@ -56,6 +56,8 @@ class CommitStatus < ActiveRecord::Base
   scope :ordered, -> { order(:ref, :stage_idx, :name) }
   scope :for_ref, ->(ref) { where(ref: ref) }
+  AVAILABLE_STATUSES = ['pending', 'running', 'success', 'failed', 'canceled']
+
   state_machine :status, initial: :pending do
     event :run do
       transition pending: :running

doc/api/README.md

@@ -23,6 +23,7 @@
 - [Namespaces](namespaces.md)
 - [Settings](settings.md)
 - [Keys](keys.md)
+- [Builds](builds.md)
 - [Build Variables](build_variables.md)
 ## Clients

doc/api/builds.md

+# Builds API
+
+## List project builds
+
+Get a list of builds in a project.
+
+```
+GET /projects/:id/builds
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| scope     | string|array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
+
+### Example of request
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds"
+```
+
+### Example of response
+
+```json
+[
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2015-12-24T15:51:21.802Z",
+        "download_url": null,
+        "finished_at": "2015-12-24T17:54:27.895Z",
+        "id": 7,
+        "name": "teaspoon",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": "2015-12-24T17:54:27.722Z",
+        "status": "failed",
+        "tag": false,
+        "user": {
+            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+            "bio": null,
+            "created_at": "2015-12-21T13:14:24.077Z",
+            "id": 1,
+            "is_admin": true,
+            "linkedin": "",
+            "name": "Administrator",
+            "skype": "",
+            "state": "active",
+            "twitter": "",
+            "username": "root",
+            "web_url": "http://gitlab.dev/u/root",
+            "website_url": ""
+        }
+    },
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2015-12-24T15:51:21.727Z",
+        "download_url": null,
+        "finished_at": "2015-12-24T17:54:24.921Z",
+        "id": 6,
+        "name": "spinach:other",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": "2015-12-24T17:54:24.729Z",
+        "status": "failed",
+        "tag": false,
+        "user": {
+            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+            "bio": null,
+            "created_at": "2015-12-21T13:14:24.077Z",
+            "id": 1,
+            "is_admin": true,
+            "linkedin": "",
+            "name": "Administrator",
+            "skype": "",
+            "state": "active",
+            "twitter": "",
+            "username": "root",
+            "web_url": "http://gitlab.dev/u/root",
+            "website_url": ""
+        }
+    }
+]
+```
+
+## List commit builds
+
+Get a list of builds for specific commit in a project.
+
+```
+GET /projects/:id/repository/commits/:sha/builds
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| sha       | string  | yes      | The SHA id of a commit |
+| scope     | string|array of strings | no | The scope of builds to show, one or array of: `pending`, `running`, `failed`, `success`, `canceled`; showing all builds if none provided |
+
+### Example of request
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/repository/commits/0ff3ae198f8601a285adcf5c0fff204ee6fba5fd/builds"
+```
+
+### Example of response
+
+```json
+[
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2016-01-11T10:13:33.506Z",
+        "download_url": null,
+        "finished_at": "2016-01-11T10:14:09.526Z",
+        "id": 69,
+        "name": "rubocop",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": null,
+        "status": "canceled",
+        "tag": false,
+        "user": null
+    },
+    {
+        "commit": {
+            "author_email": "admin@example.com",
+            "author_name": "Administrator",
+            "created_at": "2015-12-24T16:51:14.000+01:00",
+            "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+            "message": "Test the CI integration.",
+            "short_id": "0ff3ae19",
+            "title": "Test the CI integration."
+        },
+        "coverage": null,
+        "created_at": "2015-12-24T15:51:21.957Z",
+        "download_url": null,
+        "finished_at": "2015-12-24T17:54:33.913Z",
+        "id": 9,
+        "name": "brakeman",
+        "ref": "master",
+        "runner": null,
+        "stage": "test",
+        "started_at": "2015-12-24T17:54:33.727Z",
+        "status": "failed",
+        "tag": false,
+        "user": {
+            "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+            "bio": null,
+            "created_at": "2015-12-21T13:14:24.077Z",
+            "id": 1,
+            "is_admin": true,
+            "linkedin": "",
+            "name": "Administrator",
+            "skype": "",
+            "state": "active",
+            "twitter": "",
+            "username": "root",
+            "web_url": "http://gitlab.dev/u/root",
+            "website_url": ""
+        }
+    }
+]
+```
+
+## Get a single build
+
+Get a single build of a project
+
+```
+GET /projects/:id/builds/:build_id
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| build\_id  | integer | yes      | The ID of a build   |
+
+### Example of request
+
+```
+curl -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/8"
+```
+
+### Example of response
+
+```json
+{
+    "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2015-12-24T16:51:14.000+01:00",
+        "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+        "message": "Test the CI integration.",
+        "short_id": "0ff3ae19",
+        "title": "Test the CI integration."
+    },
+    "coverage": null,
+    "created_at": "2015-12-24T15:51:21.880Z",
+    "download_url": null,
+    "finished_at": "2015-12-24T17:54:31.198Z",
+    "id": 8,
+    "name": "rubocop",
+    "ref": "master",
+    "runner": null,
+    "stage": "test",
+    "started_at": "2015-12-24T17:54:30.733Z",
+    "status": "failed",
+    "tag": false,
+    "user": {
+        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+        "bio": null,
+        "created_at": "2015-12-21T13:14:24.077Z",
+        "id": 1,
+        "is_admin": true,
+        "linkedin": "",
+        "name": "Administrator",
+        "skype": "",
+        "state": "active",
+        "twitter": "",
+        "username": "root",
+        "web_url": "http://gitlab.dev/u/root",
+        "website_url": ""
+    }
+}
+```
+
+## Cancel a build
+
+Cancel a single build of a project
+
+```
+POST /projects/:id/builds/:build_id/cancel
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| build\_id | integer | yes      | The ID of a build   |
+
+### Example of request
+
+```
+curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/cancel"
+```
+
+### Example of response
+
+```json
+{
+    "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2015-12-24T16:51:14.000+01:00",
+        "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+        "message": "Test the CI integration.",
+        "short_id": "0ff3ae19",
+        "title": "Test the CI integration."
+    },
+    "coverage": null,
+    "created_at": "2016-01-11T10:13:33.506Z",
+    "download_url": null,
+    "finished_at": "2016-01-11T10:14:09.526Z",
+    "id": 69,
+    "name": "rubocop",
+    "ref": "master",
+    "runner": null,
+    "stage": "test",
+    "started_at": null,
+    "status": "canceled",
+    "tag": false,
+    "user": null
+}
+```
+
+## Retry a build
+
+Retry a single build of a project
+
+```
+POST /projects/:id/builds/:build_id/retry
+```
+
+### Parameters
+
+| Attribute | Type    | required | Description         |
+|-----------|---------|----------|---------------------|
+| id        | integer | yes      | The ID of a project |
+| build\_id | integer | yes      | The ID of a build   |
+
+### Example of request
+
+```
+curl -X POST -H "PRIVATE_TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/retry"
+```
+
+### Example of response
+
+```json
+{
+    "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2015-12-24T16:51:14.000+01:00",
+        "id": "0ff3ae198f8601a285adcf5c0fff204ee6fba5fd",
+        "message": "Test the CI integration.",
+        "short_id": "0ff3ae19",
+        "title": "Test the CI integration."
+    },
+    "coverage": null,
+    "created_at": "2016-01-11T10:13:33.506Z",
+    "download_url": null,
+    "finished_at": null,
+    "id": 69,
+    "name": "rubocop",
+    "ref": "master",
+    "runner": null,
+    "stage": "test",
+    "started_at": null,
+    "status": "pending",
+    "tag": false,
+    "user": null
+}
+```

lib/api/api.rb

@@ -54,6 +54,7 @@ module API
     mount Keys
     mount Tags
     mount Triggers
+    mount Builds
     mount Variables
   end
 end

lib/api/builds.rb

+module API
+  # Projects builds API
+  class Builds < Grape::API
+    before { authenticate! }
+
+    resource :projects do
+      # Get a project builds
+      #
+      # Parameters:
+      #   id (required) - The ID of a project
+      #   scope (optional) - The scope of builds to show (one or array of: pending, running, failed, success, canceled;
+      #                      if none provided showing all builds)
+      # Example Request:
+      #   GET /projects/:id/builds
+      get ':id/builds' do
+        builds = user_project.builds.order('id DESC')
+        builds = filter_builds(builds, params[:scope])
+
+        present paginate(builds), with: Entities::Build,
+                                  user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
+      end
+
+      # Get builds for a specific commit of a project
+      #
+      # Parameters:
+      #   id (required) - The ID of a project
+      #   sha (required) - The SHA id of a commit
+      #   scope (optional) - The scope of builds to show (one or array of: pending, running, failed, success, canceled;
+      #                      if none provided showing all builds)
+      # Example Request:
+      #   GET /projects/:id/repository/commits/:sha/builds
+      get ':id/repository/commits/:sha/builds' do
+        commit = user_project.ci_commits.find_by_sha(params[:sha])
+        return not_found! unless commit
+
+        builds = commit.builds.order('id DESC')
+        builds = filter_builds(builds, params[:scope])
+
+        present paginate(builds), with: Entities::Build,
+                                  user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
+      end
+
+      # Get a specific build of a project
+      #
+      # Parameters:
+      #   id (required) - The ID of a project
+      #   build_id (required) - The ID of a build
+      # Example Request:
+      #   GET /projects/:id/builds/:build_id
+      get ':id/builds/:build_id' do
+        build = get_build(params[:build_id])
+        return not_found!(build) unless build
+
+        present build, with: Entities::Build,
+                       user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
+      end
+
+      # Get a trace of a specific build of a project
+      #
+      # Parameters:
+      #   id (required) - The ID of a project
+      #   build_id (required) - The ID of a build
+      # Example Request:
+      #   GET /projects/:id/build/:build_id/trace
+      #
+      # TODO: We should use `present_file!` and leave this implementation for backward compatibility (when build trace
+      #       is saved in the DB instead of file). But before that, we need to consider how to replace the value of
+      #       `runners_token` with some mask (like `xxxxxx`) when sending trace file directly by workhorse.
+      get ':id/builds/:build_id/trace' do
+        build = get_build(params[:build_id])
+        return not_found!(build) unless build
+
+        header 'Content-Disposition', "infile; filename=\"#{build.id}.log\""
+        content_type 'text/plain'
+        env['api.format'] = :binary
+
+        trace = build.trace
+        body trace
+      end
+
+      # Cancel a specific build of a project
+      #
+      # parameters:
+      #   id (required) - the id of a project
+      #   build_id (required) - the id of a build
+      # example request:
+      #   post /projects/:id/build/:build_id/cancel
+      post ':id/builds/:build_id/cancel' do
+        authorize_manage_builds!
+
+        build = get_build(params[:build_id])
+        return not_found!(build) unless build
+
+        build.cancel
+
+        present build, with: Entities::Build,
+                       user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
+      end
+
+      # Retry a specific build of a project
+      #
+      # parameters:
+      #   id (required) - the id of a project
+      #   build_id (required) - the id of a build
+      # example request:
+      #   post /projects/:id/build/:build_id/retry
+      post ':id/builds/:build_id/retry' do
+        authorize_manage_builds!
+
+        build = get_build(params[:build_id])
+        return forbidden!('Build is not retryable') unless build && build.retryable?
+
+        build = Ci::Build.retry(build)
+
+        present build, with: Entities::Build,
+                       user_can_download_artifacts: can?(current_user, :download_build_artifacts, user_project)
+      end
+    end
+
+    helpers do
+      def get_build(id)
+        user_project.builds.find_by(id: id.to_i)
+      end
+
+      def filter_builds(builds, scope)
+        return builds if scope.nil? || scope.empty?
+
+        available_statuses = ::CommitStatus::AVAILABLE_STATUSES
+        scope =
+          if scope.is_a?(String)
+            [scope]
+          elsif scope.is_a?(Hashie::Mash)
+            scope.values
+          else
+            ['unknown']
+          end
+
+        unknown = scope - available_statuses
+        render_api_error!('Scope contains invalid value(s)', 400) unless unknown.empty?
+
+        builds.where(status: available_statuses && scope)
+      end
+
+      def authorize_manage_builds!
+        authorize! :manage_builds, user_project
+      end
+    end
+  end
+end

lib/api/entities.rb

@@ -367,6 +367,33 @@ module API
       expose :id, :variables
     end
+    class Runner < Grape::Entity
+      expose :id
+      expose :description
+      expose :active
+      expose :is_shared
+      expose :name
+    end
+
+    class Build < Grape::Entity
+      expose :id, :status, :stage, :name, :ref, :tag, :coverage
+      expose :created_at, :started_at, :finished_at
+      expose :user, with: User
+      # TODO: download_url in Ci:Build model is an GitLab Web Interface URL, not API URL. We should think on some API
+      #       for downloading of artifacts (see: https://gitlab.com/gitlab-org/gitlab-ce/issues/4255)
+      expose :download_url do |repo_obj, options|
+        if options[:user_can_download_artifacts]
+          repo_obj.download_url
+        end
+      end
+      expose :commit, with: RepoCommit do |repo_obj, _options|
+        if repo_obj.respond_to?(:commit)
+          repo_obj.commit.commit_data
+        end
+      end
+      expose :runner, with: Runner
+    end
+
     class Variable < Grape::Entity
       expose :key, :value
     end

spec/factories/ci/builds.rb

@@ -30,6 +30,7 @@ FactoryGirl.define do
     name 'test'
     ref 'master'
     tag false
+    created_at 'Di 29. Okt 09:50:00 CET 2013'
     started_at 'Di 29. Okt 09:51:28 CET 2013'
     finished_at 'Di 29. Okt 09:53:28 CET 2013'
     commands 'ls -a'
@@ -42,6 +43,10 @@ FactoryGirl.define do
     commit factory: :ci_commit
+    trait :canceled do
+      status 'canceled'
+    end
+
     after(:build) do |build, evaluator|
       build.project = build.commit.project
     end
@@ -54,5 +59,11 @@ FactoryGirl.define do
     factory :ci_build_tag do
       tag true
     end
+
+    factory :ci_build_with_trace do
+      after(:create) do  |build, evaluator|
+        build.trace = 'BUILD TRACE'
+      end
+    end
   end
 end

spec/requests/api/builds_spec.rb

+require 'spec_helper'
+
+describe API::API, api: true  do
+  include ApiHelpers
+
+  let(:user) { create(:user) }
+  let(:user2) { create(:user) }
+  let!(:project) { create(:project, creator_id: user.id) }
+  let!(:developer) { create(:project_member, user: user, project: project, access_level: ProjectMember::DEVELOPER) }
+  let!(:reporter) { create(:project_member, user: user2, project: project, access_level: ProjectMember::REPORTER) }
+  let(:commit) { create(:ci_commit, project: project)}
+  let(:build) { create(:ci_build, commit: commit) }
+  let(:build_with_trace) { create(:ci_build_with_trace, commit: commit) }
+  let(:build_canceled) { create(:ci_build, :canceled, commit: commit) }
+
+  describe 'GET /projects/:id/builds ' do
+    context 'authorized user' do
+      it 'should return project builds' do
+        get api("/projects/#{project.id}/builds", user)
+
+        expect(response.status).to eq(200)
+        expect(json_response).to be_an Array
+      end
+
+      it 'should filter project with one scope element' do
+        get api("/projects/#{project.id}/builds?scope=pending", user)
+
+        expect(response.status).to eq(200)
+        expect(json_response).to be_an Array
+      end
+
+      it 'should filter project with array of scope elements' do
+        get api("/projects/#{project.id}/builds?scope[0]=pending&scope[1]=running", user)
+
+        expect(response.status).to eq(200)
+        expect(json_response).to be_an Array
+      end
+
+      it 'should respond 400 when scope contains invalid state' do
+        get api("/projects/#{project.id}/builds?scope[0]=pending&scope[1]=unknown_status", user)
+
+        expect(response.status).to eq(400)
+      end
+    end
+
+    context 'unauthorized user' do
+      it 'should not return project builds' do
+        get api("/projects/#{project.id}/builds")
+
+        expect(response.status).to eq(401)
+      end
+    end
+  end
+
+  describe 'GET /projects/:id/repository/commits/:sha/builds' do
+    context 'authorized user' do
+      it 'should return project builds for specific commit' do
+        project.ensure_ci_commit(commit.sha)
+        get api("/projects/#{project.id}/repository/commits/#{commit.sha}/builds", user)
+
+        expect(response.status).to eq(200)
+        expect(json_response).to be_an Array
+      end
+    end
+
+    context 'unauthorized user' do
+      it 'should not return project builds' do
+        project.ensure_ci_commit(commit.sha)
+        get api("/projects/#{project.id}/repository/commits/#{commit.sha}/builds")
+
+        expect(response.status).to eq(401)
+      end
+    end
+  end
+
+  describe 'GET /projects/:id/builds/:build_id' do
+    context 'authorized user' do
+      it 'should return specific build data' do
+        get api("/projects/#{project.id}/builds/#{build.id}", user)
+
+        expect(response.status).to eq(200)
+        expect(json_response['name']).to eq('test')
+      end
+    end
+
+    context 'unauthorized user' do
+      it 'should not return specific build data' do
+        get api("/projects/#{project.id}/builds/#{build.id}")
+
+        expect(response.status).to eq(401)
+      end
+    end
+  end
+
+  describe 'GET /projects/:id/builds/:build_id/trace' do
+    context 'authorized user' do
+      it 'should return specific build trace' do
+        get api("/projects/#{project.id}/builds/#{build_with_trace.id}/trace", user)
+
+        expect(response.status).to eq(200)
+        expect(response.body).to eq(build_with_trace.trace)
+      end
+    end
+
+    context 'unauthorized user' do
+      it 'should not return specific build trace' do
+        get api("/projects/#{project.id}/builds/#{build_with_trace.id}/trace")
+
+        expect(response.status).to eq(401)
+      end
+    end
+  end
+
+  describe 'POST /projects/:id/builds/:build_id/cancel' do
+    context 'authorized user' do
+      context 'user with :manage_builds persmission' do
+        it 'should cancel running or pending build' do
+          post api("/projects/#{project.id}/builds/#{build.id}/cancel", user)
+
+          expect(response.status).to eq(201)
+          expect(project.builds.first.status).to eq('canceled')
+        end
+      end
+
+      context 'user without :manage_builds permission' do
+        it 'should not cancel build' do
+          post api("/projects/#{project.id}/builds/#{build.id}/cancel", user2)
+
+          expect(response.status).to eq(403)
+        end
+      end
+    end
+
+    context 'unauthorized user' do
+      it 'should not cancel build' do
+        post api("/projects/#{project.id}/builds/#{build.id}/cancel")
+
+        expect(response.status).to eq(401)
+      end
+    end
+  end
+
+  describe 'POST /projects/:id/builds/:build_id/retry' do
+    context 'authorized user' do
+      context 'user with :manage_builds persmission' do
+        it 'should retry non-running build' do
+          post api("/projects/#{project.id}/builds/#{build_canceled.id}/retry", user)
+
+          expect(response.status).to eq(201)
+          expect(project.builds.first.status).to eq('canceled')
+          expect(json_response['status']).to eq('pending')
+        end
+      end
+
+      context 'user without :manage_builds permission' do
+        it 'should not retry build' do
+          post api("/projects/#{project.id}/builds/#{build_canceled.id}/retry", user2)
+
+          expect(response.status).to eq(403)
+        end
+      end
+    end
+
+    context 'unauthorized user' do
+      it 'should not retry build' do
+        post api("/projects/#{project.id}/builds/#{build_canceled.id}/retry")
+
+        expect(response.status).to eq(401)
+      end
+    end
+  end
+end