Merge branch 'zj-api-endpoints-ci' into 'master'

Deployment and Play endpoints

See merge request !5825

CHANGELOG

@@ -30,6 +30,8 @@ v 8.11.0 (unreleased)
   - Expand commit message width in repo view (ClemMakesApps)
   - Cache highlighted diff lines for merge requests
   - Pre-create all builds for a Pipeline when the new Pipeline is created !5295
+  - API: Add deployment endpoints
+  - API: Add Play endpoint on Builds
   - Fix of 'Commits being passed to custom hooks are already reachable when using the UI'
   - Show member roles to all users on members page
   - Project.visible_to_user is instrumented again

doc/api/builds.md

@@ -532,3 +532,49 @@ Example response:
   "user": null
 }
 ```
+
+## Play a build
+
+Triggers a manual action to start a build.
+
+```
+POST /projects/:id/builds/:build_id/play
+```
+
+| Attribute  | Type    | Required | Description         |
+|------------|---------|----------|---------------------|
+| `id`       | integer | yes      | The ID of a project |
+| `build_id` | integer | yes      | The ID of a build   |
+
+```
+curl --request POST --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/builds/1/play"
+```
+
+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",
+  "artifacts_file": null,
+  "finished_at": null,
+  "id": 69,
+  "name": "rubocop",
+  "ref": "master",
+  "runner": null,
+  "stage": "test",
+  "started_at": null,
+  "status": "started",
+  "tag": false,
+  "user": null
+}
+```

doc/api/deployments.md

+# Deployments API
+
+## List project deployments
+
+Get a list of deployments in a project.
+
+```
+GET /projects/:id/deployments
+```
+
+| Attribute | Type    | Required | Description         |
+|-----------|---------|----------|---------------------|
+| `id`      | integer | yes      | The ID of a project |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/deployments"
+```
+
+Example of response
+
+```json
+[
+  {
+    "created_at": "2016-08-11T07:36:40.222Z",
+    "deployable": {
+      "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2016-08-11T09:36:01.000+02:00",
+        "id": "99d03678b90d914dbb1b109132516d71a4a03ea8",
+        "message": "Merge branch 'new-title' into 'master'\r\n\r\nUpdate README\r\n\r\n\r\n\r\nSee merge request !1",
+        "short_id": "99d03678",
+        "title": "Merge branch 'new-title' into 'master'\r"
+      },
+      "coverage": null,
+      "created_at": "2016-08-11T07:36:27.357Z",
+      "finished_at": "2016-08-11T07:36:39.851Z",
+      "id": 657,
+      "name": "deploy",
+      "ref": "master",
+      "runner": null,
+      "stage": "deploy",
+      "started_at": null,
+      "status": "success",
+      "tag": false,
+      "user": {
+        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+        "bio": null,
+        "created_at": "2016-08-11T07:09:20.351Z",
+        "id": 1,
+        "is_admin": true,
+        "linkedin": "",
+        "location": null,
+        "name": "Administrator",
+        "skype": "",
+        "state": "active",
+        "twitter": "",
+        "username": "root",
+        "web_url": "http://localhost:3000/u/root",
+        "website_url": ""
+      }
+    },
+    "environment": {
+      "external_url": "https://about.gitlab.com",
+      "id": 9,
+      "name": "production"
+    },
+    "id": 41,
+    "iid": 1,
+    "ref": "master",
+    "sha": "99d03678b90d914dbb1b109132516d71a4a03ea8",
+    "user": {
+      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+      "id": 1,
+      "name": "Administrator",
+      "state": "active",
+      "username": "root",
+      "web_url": "http://localhost:3000/u/root"
+    }
+  },
+  {
+    "created_at": "2016-08-11T11:32:35.444Z",
+    "deployable": {
+      "commit": {
+        "author_email": "admin@example.com",
+        "author_name": "Administrator",
+        "created_at": "2016-08-11T13:28:26.000+02:00",
+        "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
+        "message": "Merge branch 'rename-readme' into 'master'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2",
+        "short_id": "a91957a8",
+        "title": "Merge branch 'rename-readme' into 'master'\r"
+      },
+      "coverage": null,
+      "created_at": "2016-08-11T11:32:24.456Z",
+      "finished_at": "2016-08-11T11:32:35.145Z",
+      "id": 664,
+      "name": "deploy",
+      "ref": "master",
+      "runner": null,
+      "stage": "deploy",
+      "started_at": null,
+      "status": "success",
+      "tag": false,
+      "user": {
+        "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+        "bio": null,
+        "created_at": "2016-08-11T07:09:20.351Z",
+        "id": 1,
+        "is_admin": true,
+        "linkedin": "",
+        "location": null,
+        "name": "Administrator",
+        "skype": "",
+        "state": "active",
+        "twitter": "",
+        "username": "root",
+        "web_url": "http://localhost:3000/u/root",
+        "website_url": ""
+      }
+    },
+    "environment": {
+      "external_url": "https://about.gitlab.com",
+      "id": 9,
+      "name": "production"
+    },
+    "id": 42,
+    "iid": 2,
+    "ref": "master",
+    "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
+    "user": {
+      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+      "id": 1,
+      "name": "Administrator",
+      "state": "active",
+      "username": "root",
+      "web_url": "http://localhost:3000/u/root"
+    }
+  }
+]
+```
+
+## Get a specific deployment
+
+```
+GET /projects/:id/deployments/:deployment_id
+```
+
+| Attribute | Type    | Required | Description         |
+|-----------|---------|----------|---------------------|
+| `id`      | integer | yes      | The ID of a project |
+| `deployment_id` | integer | yes      | The ID of the deployment |
+
+```bash
+curl --header "PRIVATE-TOKEN: 9koXpg98eAheJpvBs5tK" "https://gitlab.example.com/api/v3/projects/1/deployments/1"
+```
+
+Example of response
+
+```json
+{
+  "id": 42,
+  "iid": 2,
+  "ref": "master",
+  "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
+  "created_at": "2016-08-11T11:32:35.444Z",
+  "user": {
+    "name": "Administrator",
+    "username": "root",
+    "id": 1,
+    "state": "active",
+    "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+    "web_url": "http://localhost:3000/u/root"
+  },
+  "environment": {
+    "id": 9,
+    "name": "production",
+    "external_url": "https://about.gitlab.com"
+  },
+  "deployable": {
+    "id": 664,
+    "status": "success",
+    "stage": "deploy",
+    "name": "deploy",
+    "ref": "master",
+    "tag": false,
+    "coverage": null,
+    "created_at": "2016-08-11T11:32:24.456Z",
+    "started_at": null,
+    "finished_at": "2016-08-11T11:32:35.145Z",
+    "user": {
+      "name": "Administrator",
+      "username": "root",
+      "id": 1,
+      "state": "active",
+      "avatar_url": "http://www.gravatar.com/avatar/e64c7d89f26bd1972efa854d13d7dd61?s=80&d=identicon",
+      "web_url": "http://localhost:3000/u/root",
+      "created_at": "2016-08-11T07:09:20.351Z",
+      "is_admin": true,
+      "bio": null,
+      "location": null,
+      "skype": "",
+      "linkedin": "",
+      "twitter": "",
+      "website_url": ""
+    },
+    "commit": {
+      "id": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
+      "short_id": "a91957a8",
+      "title": "Merge branch 'rename-readme' into 'master'\r",
+      "author_name": "Administrator",
+      "author_email": "admin@example.com",
+      "created_at": "2016-08-11T13:28:26.000+02:00",
+      "message": "Merge branch 'rename-readme' into 'master'\r\n\r\nRename README\r\n\r\n\r\n\r\nSee merge request !2"
+    },
+    "runner": null
+  }
+}
+```

lib/api/api.rb

@@ -43,6 +43,7 @@ module API
     mount ::API::CommitStatuses
     mount ::API::Commits
     mount ::API::DeployKeys
+    mount ::API::Deployments
     mount ::API::Environments
     mount ::API::Files
     mount ::API::Groups

lib/api/builds.rb

@@ -189,6 +189,27 @@ module API
         present build, with: Entities::Build,
                        user_can_download_artifacts: can?(current_user, :read_build, user_project)
       end
+
+      desc 'Trigger a manual build' do
+        success Entities::Build
+        detail 'This feature was added in GitLab 8.11'
+      end
+      params do
+        requires :build_id, type: Integer, desc: 'The ID of a Build'
+      end
+      post ":id/builds/:build_id/play" do
+        authorize_read_builds!
+
+        build = get_build!(params[:build_id])
+
+        bad_request!("Unplayable Build") unless build.playable?
+
+        build.play(current_user)
+
+        status 200
+        present build, with: Entities::Build,
+                       user_can_download_artifacts: can?(current_user, :read_build, user_project)
+      end
     end
 
     helpers do

lib/api/deployments.rb

+module API
+  # Deployments RESTfull API endpoints
+  class Deployments < Grape::API
+    before { authenticate! }
+
+    params do
+      requires :id, type: String, desc: 'The project ID'
+    end
+    resource :projects do
+      desc 'Get all deployments of the project' do
+        detail 'This feature was introduced in GitLab 8.11.'
+        success Entities::Deployment
+      end
+      params do
+        optional :page,     type: Integer, desc: 'Page number of the current request'
+        optional :per_page, type: Integer, desc: 'Number of items per page'
+      end
+      get ':id/deployments' do
+        authorize! :read_deployment, user_project
+
+        present paginate(user_project.deployments), with: Entities::Deployment
+      end
+
+      desc 'Gets a specific deployment' do
+        detail 'This feature was introduced in GitLab 8.11.'
+        success Entities::Deployment
+      end
+      params do
+        requires :deployment_id, type: Integer,  desc: 'The deployment ID'
+      end
+      get ':id/deployments/:deployment_id' do
+        authorize! :read_deployment, user_project
+
+        deployment = user_project.deployments.find(params[:deployment_id])
+
+        present deployment, with: Entities::Deployment
+      end
+    end
+  end
+end

lib/api/entities.rb

@@ -512,6 +512,18 @@ module API
 
     class Environment < Grape::Entity
       expose :id, :name, :external_url
+      expose :project, using: Entities::Project
+    end
+
+    class EnvironmentBasic < Grape::Entity
+      expose :id, :name, :external_url
+    end
+
+    class Deployment < Grape::Entity
+      expose :id, :iid, :ref, :sha, :created_at
+      expose :user,        using: Entities::UserBasic
+      expose :environment, using: Entities::EnvironmentBasic
+      expose :deployable,  using: Entities::Build
     end
 
     class RepoLicense < Grape::Entity

spec/requests/api/builds_spec.rb

@@ -407,4 +407,27 @@ describe API::API, api: true do
       end
     end
   end
+
+  describe 'POST /projects/:id/builds/:build_id/play' do
+    before do
+      post api("/projects/#{project.id}/builds/#{build.id}/play", user)
+    end
+
+    context 'on an playable build' do
+      let(:build) { create(:ci_build, :manual, project: project, pipeline: pipeline) }
+
+      it 'plays the build' do
+        expect(response).to have_http_status 200
+        expect(json_response['user']['id']).to eq(user.id)
+        expect(json_response['id']).to eq(build.id)
+      end
+    end
+
+    context 'on a non-playable build' do
+      it 'returns a status code 400, Bad Request' do
+        expect(response).to have_http_status 400
+        expect(response.body).to match("Unplayable Build")
+      end
+    end
+  end
 end

spec/requests/api/deployments_spec.rb

+require 'spec_helper'
+
+describe API::API, api: true  do
+  include ApiHelpers
+
+  let(:user)        { create(:user) }
+  let(:non_member)  { create(:user) }
+  let(:project)     { deployment.environment.project }
+  let!(:deployment) { create(:deployment) }
+
+  before do
+    project.team << [user, :master]
+  end
+
+  describe 'GET /projects/:id/deployments' do
+    context 'as member of the project' do
+      it_behaves_like 'a paginated resources' do
+        let(:request) { get api("/projects/#{project.id}/deployments", user) }
+      end
+
+      it 'returns projects deployments' do
+        get api("/projects/#{project.id}/deployments", user)
+
+        expect(response).to have_http_status(200)
+        expect(json_response).to be_an Array
+        expect(json_response.size).to eq(1)
+        expect(json_response.first['iid']).to eq(deployment.iid)
+        expect(json_response.first['sha']).to match /\A\h{40}\z/
+      end
+    end
+
+    context 'as non member' do
+      it 'returns a 404 status code' do
+        get api("/projects/#{project.id}/deployments", non_member)
+
+        expect(response).to have_http_status(404)
+      end
+    end
+  end
+
+  describe 'GET /projects/:id/deployments/:deployment_id' do
+    context 'as a member of the project' do
+      it 'returns the projects deployment' do
+        get api("/projects/#{project.id}/deployments/#{deployment.id}", user)
+
+        expect(response).to have_http_status(200)
+        expect(json_response['sha']).to match /\A\h{40}\z/
+        expect(json_response['id']).to eq(deployment.id)
+      end
+    end
+
+    context 'as non member' do
+      it 'returns a 404 status code' do
+        get api("/projects/#{project.id}/deployments/#{deployment.id}", non_member)
+
+        expect(response).to have_http_status(404)
+      end
+    end
+  end
+end

spec/requests/api/environments_spec.rb

@@ -26,6 +26,7 @@ describe API::API, api: true  do
         expect(json_response.size).to eq(1)
         expect(json_response.first['name']).to eq(environment.name)
         expect(json_response.first['external_url']).to eq(environment.external_url)
+        expect(json_response.first['project']['id']).to eq(project.id)
       end
     end