Merge branch 'deployments-api' into 'master'

Add API for manually creating deployments

Closes #25176 and #32579

See merge request gitlab-org/gitlab!17620

app/controllers/projects/deployments_controller.rb

@@ -47,11 +47,9 @@ class Projects::DeploymentsController < Projects::ApplicationController
     @deployment_metrics ||= DeploymentMetrics.new(deployment.project, deployment)
   end
 
-  # rubocop: disable CodeReuse/ActiveRecord
   def deployment
-    @deployment ||= environment.deployments.find_by(iid: params[:id])
+    @deployment ||= environment.deployments.find_successful_deployment!(params[:id])
   end
-  # rubocop: enable CodeReuse/ActiveRecord
 
   def environment
     @environment ||= project.environments.find(params[:environment_id])

app/helpers/environment_helper.rb

@@ -18,12 +18,16 @@ module EnvironmentHelper
     end
   end
 
+  def deployment_path(deployment)
+    [deployment.project.namespace.becomes(Namespace), deployment.project, deployment.deployable]
+  end
+
   def deployment_link(deployment, text: nil)
     return unless deployment
 
     link_label = text ? text : "##{deployment.iid}"
 
-    link_to link_label, [deployment.project.namespace.becomes(Namespace), deployment.project, deployment.deployable]
+    link_to link_label, deployment_path(deployment)
   end
 
   def last_deployment_link_for_environment_build(project, build)
@@ -32,4 +36,31 @@ module EnvironmentHelper
 
     deployment_link(environment.last_deployment)
   end
+
+  def render_deployment_status(deployment)
+    status = deployment.status
+
+    status_text =
+      case status
+      when 'created'
+        s_('Deployment|created')
+      when 'running'
+        s_('Deployment|running')
+      when 'success'
+        s_('Deployment|success')
+      when 'failed'
+        s_('Deployment|failed')
+      when 'canceled'
+        s_('Deployment|canceled')
+      end
+
+    klass = "ci-status ci-#{status.dasherize}"
+    text = "#{ci_icon_for_status(status)} #{status_text}".html_safe
+
+    if deployment.deployable
+      link_to(text, deployment_path(deployment), class: klass)
+    else
+      content_tag(:span, text, class: klass)
+    end
+  end
 end

app/models/deployment.rb

@@ -9,7 +9,7 @@ class Deployment < ApplicationRecord
   belongs_to :environment, required: true
   belongs_to :cluster, class_name: 'Clusters::Cluster', optional: true
   belongs_to :user
-  belongs_to :deployable, polymorphic: true # rubocop:disable Cop/PolymorphicAssociations
+  belongs_to :deployable, polymorphic: true, optional: true # rubocop:disable Cop/PolymorphicAssociations
 
   has_internal_id :iid, scope: :project, init: ->(s) do
     Deployment.where(project: s.project).maximum(:iid) if s&.project
@@ -22,6 +22,8 @@ class Deployment < ApplicationRecord
 
   scope :for_environment, -> (environment) { where(environment_id: environment) }
 
+  scope :visible, -> { where(status: %i[running success failed canceled]) }
+
   state_machine :status, initial: :created do
     event :run do
       transition created: :running
@@ -73,6 +75,10 @@ class Deployment < ApplicationRecord
     find(ids)
   end
 
+  def self.find_successful_deployment!(iid)
+    success.find_by!(iid: iid)
+  end
+
   def commit
     project.commit(sha)
   end

app/models/environment.rb

@@ -6,7 +6,8 @@ class Environment < ApplicationRecord
 
   belongs_to :project, required: true
 
-  has_many :deployments, -> { success }, dependent: :destroy # rubocop:disable Cop/ActiveRecordDependent
+  has_many :deployments, -> { visible }, dependent: :destroy # rubocop:disable Cop/ActiveRecordDependent
+  has_many :successful_deployments, -> { success }, class_name: 'Deployment'
 
   has_one :last_deployment, -> { success.order('deployments.id DESC') }, class_name: 'Deployment'
 
@@ -81,6 +82,10 @@ class Environment < ApplicationRecord
     pluck(:name)
   end
 
+  def self.find_or_create_by_name(name)
+    find_or_create_by(name: name)
+  end
+
   def predefined_variables
     Gitlab::Ci::Variables::Collection.new
       .append(key: 'CI_ENVIRONMENT_NAME', value: name)

app/models/project.rb

@@ -281,7 +281,7 @@ class Project < ApplicationRecord
   has_many :variables, class_name: 'Ci::Variable'
   has_many :triggers, class_name: 'Ci::Trigger'
   has_many :environments
-  has_many :deployments, -> { success }
+  has_many :deployments
   has_many :pipeline_schedules, class_name: 'Ci::PipelineSchedule'
   has_many :project_deploy_tokens
   has_many :deploy_tokens, through: :project_deploy_tokens

app/policies/deployment_policy.rb

@@ -7,8 +7,20 @@ class DeploymentPolicy < BasePolicy
     can?(:update_build, @subject.deployable)
   end
 
-  rule { ~can_retry_deployable }.policy do
+  condition(:has_deployable) do
+    @subject.deployable.present?
+  end
+
+  condition(:can_update_deployment) do
+    can?(:update_deployment, @subject.environment)
+  end
+
+  rule { has_deployable & ~can_retry_deployable }.policy do
     prevent :create_deployment
     prevent :update_deployment
   end
+
+  rule { ~can_update_deployment }.policy do
+    prevent :update_deployment
+  end
 end

app/policies/project_policy.rb

@@ -262,6 +262,7 @@ class ProjectPolicy < BasePolicy
     enable :destroy_container_image
     enable :create_environment
     enable :create_deployment
+    enable :update_deployment
     enable :create_release
     enable :update_release
   end

app/services/deployments/after_create_service.rb

+# frozen_string_literal: true
+
+module Deployments
+  class AfterCreateService
+    attr_reader :deployment
+    attr_reader :deployable
+
+    delegate :environment, to: :deployment
+    delegate :variables, to: :deployable
+    delegate :options, to: :deployable, allow_nil: true
+
+    def initialize(deployment)
+      @deployment = deployment
+      @deployable = deployment.deployable
+    end
+
+    def execute
+      deployment.create_ref
+      deployment.invalidate_cache
+
+      update_environment(deployment)
+
+      deployment
+    end
+
+    def update_environment(deployment)
+      ActiveRecord::Base.transaction do
+        if (url = expanded_environment_url)
+          environment.external_url = url
+        end
+
+        environment.fire_state_event(action)
+
+        if environment.save && !environment.stopped?
+          deployment.update_merge_request_metrics!
+        end
+      end
+    end
+
+    private
+
+    def environment_options
+      options&.dig(:environment) || {}
+    end
+
+    def expanded_environment_url
+      ExpandVariables.expand(environment_url, -> { variables }) if environment_url
+    end
+
+    def environment_url
+      environment_options[:url]
+    end
+
+    def action
+      environment_options[:action] || 'start'
+    end
+  end
+end
+
+Deployments::AfterCreateService.prepend_if_ee('EE::Deployments::AfterCreateService')

app/services/deployments/create_service.rb

+# frozen_string_literal: true
+
+module Deployments
+  class CreateService
+    attr_reader :environment, :current_user, :params
+
+    def initialize(environment, current_user, params)
+      @environment = environment
+      @current_user = current_user
+      @params = params
+    end
+
+    def execute
+      create_deployment.tap do |deployment|
+        AfterCreateService.new(deployment).execute if deployment.persisted?
+      end
+    end
+
+    def create_deployment
+      environment.deployments.create(deployment_attributes)
+    end
+
+    def deployment_attributes
+      # We use explicit parameters here so we never by accident allow parameters
+      # to be set that one should not be able to set (e.g. the row ID).
+      {
+        cluster_id: environment.deployment_platform&.cluster_id,
+        project_id: environment.project_id,
+        environment_id: environment.id,
+        ref: params[:ref],
+        tag: params[:tag],
+        sha: params[:sha],
+        user: current_user,
+        on_stop: params[:on_stop],
+        status: params[:status]
+      }
+    end
+  end
+end

app/services/deployments/update_service.rb

+# frozen_string_literal: true
+
+module Deployments
+  class UpdateService
+    attr_reader :deployment, :params
+
+    def initialize(deployment, params)
+      @deployment = deployment
+      @params = params
+    end
+
+    def execute
+      deployment.update(status: params[:status])
+    end
+  end
+end

app/services/update_deployment_service.rb

-# frozen_string_literal: true
-
-class UpdateDeploymentService
-  attr_reader :deployment
-  attr_reader :deployable
-
-  delegate :environment, to: :deployment
-  delegate :variables, to: :deployable
-
-  def initialize(deployment)
-    @deployment = deployment
-    @deployable = deployment.deployable
-  end
-
-  def execute
-    deployment.create_ref
-    deployment.invalidate_cache
-
-    ActiveRecord::Base.transaction do
-      environment.external_url = expanded_environment_url if
-        expanded_environment_url
-
-      environment.fire_state_event(action)
-
-      break unless environment.save
-      break if environment.stopped?
-
-      deployment.tap(&:update_merge_request_metrics!)
-    end
-
-    deployment
-  end
-
-  private
-
-  def environment_options
-    @environment_options ||= deployable.options&.dig(:environment) || {}
-  end
-
-  def expanded_environment_url
-    return @expanded_environment_url if defined?(@expanded_environment_url)
-    return unless environment_url
-
-    @expanded_environment_url =
-      ExpandVariables.expand(environment_url, -> { variables })
-  end
-
-  def environment_url
-    environment_options[:url]
-  end
-
-  def action
-    environment_options[:action] || 'start'
-  end
-end
-
-UpdateDeploymentService.prepend_if_ee('EE::UpdateDeploymentService')

app/views/projects/deployments/_deployment.html.haml

 .gl-responsive-table-row.deployment{ role: 'row' }
+  .table-section.section-15{ role: 'gridcell' }
+    .table-mobile-header{ role: 'rowheader' }= _("Status")
+    .table-mobile-content
+      = render_deployment_status(deployment)
+
   .table-section.section-10{ role: 'gridcell' }
     .table-mobile-header{ role: 'rowheader' }= _("ID")
     %strong.table-mobile-content ##{deployment.iid}
 
-  .table-section.section-30{ role: 'gridcell' }
+  .table-section.section-10{ role: 'gridcell' }
+    .table-mobile-header{ role: 'rowheader' }= _("Triggerer")
+    .table-mobile-content
+      - if deployment.deployed_by
+        = user_avatar(user: deployment.deployed_by, size: 26, css_class: "mr-0 float-none")
+
+  .table-section.section-25{ role: 'gridcell' }
     .table-mobile-header{ role: 'rowheader' }= _("Commit")
     = render 'projects/deployments/commit', deployment: deployment
 
-  .table-section.section-25.build-column{ role: 'gridcell' }
+  .table-section.section-10.build-column{ role: 'gridcell' }
     .table-mobile-header{ role: 'rowheader' }= _("Job")
     - if deployment.deployable
       .table-mobile-content
         .flex-truncate-parent
           .flex-truncate-child
-            = link_to [@project.namespace.becomes(Namespace), @project, deployment.deployable], class: 'build-link' do
+            = link_to deployment_path(deployment), class: 'build-link' do
               #{deployment.deployable.name} (##{deployment.deployable.id})
-        - if deployment.deployed_by
-          %div
-            by
-            = user_avatar(user: deployment.deployed_by, size: 20, css_class: "mr-0 float-none")
+    - else
+      .badge.badge-info.suggestion-help-hover{ title: s_('Deployment|This deployment was created using the API') }
+        = s_('Deployment|API')
 
-  .table-section.section-15{ role: 'gridcell' }
+  .table-section.section-10{ role: 'gridcell' }
     .table-mobile-header{ role: 'rowheader' }= _("Created")
+    %span.table-mobile-content.flex-truncate-parent
+      %span.flex-truncate-child
+        = time_ago_with_tooltip(deployment.created_at)
+
+  .table-section.section-10{ role: 'gridcell' }
+    .table-mobile-header{ role: 'rowheader' }= _("Deployed")
     - if deployment.deployed_at
-      %span.table-mobile-content= time_ago_with_tooltip(deployment.deployed_at)
+      %span.table-mobile-content.flex-truncate-parent
+        %span.flex-truncate-child
+          = time_ago_with_tooltip(deployment.deployed_at)
 
-  .table-section.section-20.table-button-footer{ role: 'gridcell' }
+  .table-section.section-10.table-button-footer{ role: 'gridcell' }
     .btn-group.table-action-buttons
       = render 'projects/deployments/actions', deployment: deployment
       = render 'projects/deployments/rollback', deployment: deployment

app/views/projects/deployments/_rollback.haml

-- if can?(current_user, :create_deployment, deployment)
+- if deployment.deployable && can?(current_user, :create_deployment, deployment)
   - tooltip = deployment.last? ? s_('Environments|Re-deploy to environment') : s_('Environments|Rollback environment')
   = button_tag class: 'btn btn-default btn-build has-tooltip', type: 'button', data: { toggle: 'modal', target: "#confirm-rollback-modal-#{deployment.id}" }, title: tooltip do
     - if deployment.last?

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

@@ -60,10 +60,13 @@
     .table-holder
       .ci-table.environments{ role: 'grid' }
         .gl-responsive-table-row.table-row-header{ role: 'row' }
+          .table-section.section-15{ role: 'columnheader' }= _('Status')
           .table-section.section-10{ role: 'columnheader' }= _('ID')
-          .table-section.section-30{ role: 'columnheader' }= _('Commit')
-          .table-section.section-25{ role: 'columnheader' }= _('Job')
-          .table-section.section-15{ role: 'columnheader' }= _('Created')
+          .table-section.section-10{ role: 'columnheader' }= _('Triggerer')
+          .table-section.section-25{ role: 'columnheader' }= _('Commit')
+          .table-section.section-10{ role: 'columnheader' }= _('Job')
+          .table-section.section-10{ role: 'columnheader' }= _('Created')
+          .table-section.section-10{ role: 'columnheader' }= _('Deployed')
 
         = render @deployments
 

app/workers/deployments/success_worker.rb

@@ -10,7 +10,7 @@ module Deployments
       Deployment.find_by_id(deployment_id).try do |deployment|
         break unless deployment.success?
 
-        UpdateDeploymentService.new(deployment).execute
+        Deployments::AfterCreateService.new(deployment).execute
       end
     end
   end

changelogs/unreleased/deployments-api.yml

+---
+title: Add API for manually creating and updating deployments
+merge_request: 17620
+author:
+type: added

doc/api/deployments.md

@@ -223,3 +223,100 @@ Example of response
   }
 }
 ```
+
+## Create a deployment
+
+```
+POST /projects/:id/deployments
+```
+
+| Attribute        | Type           | Required | Description         |
+|------------------|----------------|----------|---------------------|
+| `id`             | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `environment`    | string         | yes      | The name of the environment to create the deployment for |
+| `sha`            | string         | yes      | The SHA of the commit that is deployed |
+| `ref`            | string         | yes      | The name of the branch or tag that is deployed |
+| `tag`            | boolean        | yes      | A boolean that indicates if the deployed ref is a tag (true) or not (false) |
+| `status`         | string         | yes      | The status of the deployment |
+
+The status can be one of the following values:
+
+- created
+- running
+- success
+- failed
+- canceled
+
+```bash
+curl --data "environment=production&sha=a91957a858320c0e17f3a0eca7cfacbff50ea29a&ref=master&tag=false&status=success" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments"
+```
+
+Example of a response:
+
+```json
+{
+  "id": 42,
+  "iid": 2,
+  "ref": "master",
+  "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
+  "created_at": "2016-08-11T11:32:35.444Z",
+  "status": "success",
+  "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/root"
+  },
+  "environment": {
+    "id": 9,
+    "name": "production",
+    "external_url": "https://about.gitlab.com"
+  },
+  "deployable": null
+}
+```
+
+## Updating a deployment
+
+```
+PUT /projects/:id/deployments/:deployment_id
+```
+
+| Attribute        | Type           | Required | Description         |
+|------------------|----------------|----------|---------------------|
+| `id`             | integer/string | yes      | The ID or [URL-encoded path of the project](README.md#namespaced-path-encoding) owned by the authenticated user |
+| `deployment_id`  | integer        | yes      | The ID of the deployment to update |
+| `status`         | string         | yes      | The new status of the deployment |
+
+```bash
+curl --request PUT --data "status=success" --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/projects/1/deployments/42"
+```
+
+Example of a response:
+
+```json
+{
+  "id": 42,
+  "iid": 2,
+  "ref": "master",
+  "sha": "a91957a858320c0e17f3a0eca7cfacbff50ea29a",
+  "created_at": "2016-08-11T11:32:35.444Z",
+  "status": "success",
+  "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/root"
+  },
+  "environment": {
+    "id": 9,
+    "name": "production",
+    "external_url": "https://about.gitlab.com"
+  },
+  "deployable": null
+}
+```

ee/app/models/ee/environment.rb

@@ -25,7 +25,7 @@ module EE
           .on(join_conditions)
 
         model
-          .joins(:deployments)
+          .joins(:successful_deployments)
           .joins(join.join_sources)
           .where(later_deployments[:id].eq(nil))
           .where(deployments[:cluster_id].eq(cluster.id))

ee/app/policies/ee/environment_policy.rb

@@ -9,6 +9,8 @@ module EE
       rule { ~deployable_by_user }.policy do
         prevent :stop_environment
         prevent :create_environment_terminal
+        prevent :create_deployment
+        prevent :update_deployment
       end
 
       private

ee/app/services/ee/deployments/after_create_service.rb

+# frozen_string_literal: true
+
+module EE
+  module Deployments
+    module AfterCreateService
+      extend ::Gitlab::Utils::Override
+
+      override :execute
+      def execute
+        super.tap do |deployment|
+          deployment.project.repository.log_geo_updated_event
+        end
+      end
+    end
+  end
+end

ee/app/services/ee/update_deployment_service.rb

-# frozen_string_literal: true
-
-module EE
-  module UpdateDeploymentService
-    extend ::Gitlab::Utils::Override
-
-    override :execute
-    def execute
-      super.tap do |deployment|
-        deployment.project.repository.log_geo_updated_event
-      end
-    end
-  end
-end

ee/spec/requests/api/deployments_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe API::Deployments do
+  let(:user) { create(:user) }
+  let!(:project) { create(:project, :repository) }
+  let!(:environment) { create(:environment, project: project) }
+
+  before do
+    stub_licensed_features(protected_environments: true)
+  end
+
+  describe 'POST /projects/:id/deployments' do
+    context 'when deploying to a protected environment that requires maintainer access' do
+      before do
+        create(
+          :protected_environment,
+          :maintainers_can_deploy,
+          project: environment.project,
+          name: environment.name
+        )
+      end
+
+      it 'returns a 403 when the user is a developer' do
+        project.add_developer(user)
+
+        post(
+          api("/projects/#{project.id}/deployments", user),
+          params: {
+            environment: environment.name,
+            sha: 'b83d6e391c22777fca1ed3012fce84f633d7fed0',
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(403)
+      end
+
+      it 'creates the deployment when the user is a maintainer' do
+        project.add_maintainer(user)
+
+        post(
+          api("/projects/#{project.id}/deployments", user),
+          params: {
+            environment: environment.name,
+            sha: 'b83d6e391c22777fca1ed3012fce84f633d7fed0',
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(201)
+      end
+    end
+
+    context 'when deploying to a protected environment that requires developer access' do
+      before do
+        create(
+          :protected_environment,
+          :developers_can_deploy,
+          project: environment.project,
+          name: environment.name
+        )
+      end
+
+      it 'returns a 403 when the user is a guest' do
+        project.add_guest(user)
+
+        post(
+          api("/projects/#{project.id}/deployments", user),
+          params: {
+            environment: environment.name,
+            sha: 'b83d6e391c22777fca1ed3012fce84f633d7fed0',
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(403)
+      end
+
+      it 'creates the deployment when the user is a developer' do
+        project.add_developer(user)
+
+        post(
+          api("/projects/#{project.id}/deployments", user),
+          params: {
+            environment: environment.name,
+            sha: 'b83d6e391c22777fca1ed3012fce84f633d7fed0',
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(201)
+      end
+    end
+  end
+
+  describe 'PUT /projects/:id/deployments/:deployment_id' do
+    let(:project) { create(:project) }
+    let(:deploy) do
+      create(
+        :deployment,
+        :running,
+        project: project,
+        deployable: nil,
+        environment: environment
+      )
+    end
+
+    context 'when updating a deployment for a protected environment that requires maintainer access' do
+      before do
+        create(
+          :protected_environment,
+          :maintainers_can_deploy,
+          project: environment.project,
+          name: environment.name
+        )
+      end
+
+      it 'returns a 403 when the user is a developer' do
+        project.add_developer(user)
+
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", user),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(403)
+      end
+
+      it 'updates the deployment when the user is a maintainer' do
+        project.add_maintainer(user)
+
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", user),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(200)
+      end
+    end
+
+    context 'when updating a deployment for a protected environment that requires developer access' do
+      before do
+        create(
+          :protected_environment,
+          :developers_can_deploy,
+          project: environment.project,
+          name: environment.name
+        )
+      end
+
+      it 'returns a 403 when the user is a guest' do
+        project.add_guest(user)
+
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", user),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(403)
+      end
+
+      it 'updates the deployment when the user is a developer' do
+        project.add_developer(user)
+
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", user),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(200)
+      end
+    end
+  end
+end

ee/spec/services/ee/update_deployment_service_spec.rb → ee/spec/services/ee/deployments/after_create_service_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe UpdateDeploymentService do
+describe Deployments::AfterCreateService do
   include ::EE::GeoHelpers
 
   let(:primary) { create(:geo_node, :primary) }

lib/api/deployments.rb

@@ -42,6 +42,88 @@ module API
 
         present deployment, with: Entities::Deployment
       end
+
+      desc 'Creates a new deployment' do
+        detail 'This feature was introduced in GitLab 12.4'
+        success Entities::Deployment
+      end
+      params do
+        requires :environment,
+          type: String,
+          desc: 'The name of the environment to deploy to'
+
+        requires :sha,
+          type: String,
+          desc: 'The SHA of the commit that was deployed'
+
+        requires :ref,
+          type: String,
+          desc: 'The name of the branch or tag that was deployed'
+
+        requires :tag,
+          type: Boolean,
+          desc: 'A boolean indicating if the deployment ran for a tag'
+
+        requires :status,
+          type: String,
+          desc: 'The status of the deployment',
+          values: %w[running success failed canceled]
+      end
+      post ':id/deployments' do
+        authorize!(:create_deployment, user_project)
+        authorize!(:create_environment, user_project)
+
+        environment = user_project
+          .environments
+          .find_or_create_by_name(params[:environment])
+
+        unless environment.persisted?
+          render_validation_error!(deployment)
+        end
+
+        authorize!(:create_deployment, environment)
+
+        service = ::Deployments::CreateService
+          .new(environment, current_user, declared_params)
+
+        deployment = service.execute
+
+        if deployment.persisted?
+          present(deployment, with: Entities::Deployment, current_user: current_user)
+        else
+          render_validation_error!(deployment)
+        end
+      end
+
+      desc 'Updates an existing deployment' do
+        detail 'This feature was introduced in GitLab 12.4'
+        success Entities::Deployment
+      end
+      params do
+        requires :status,
+          type: String,
+          desc: 'The new status of the deployment',
+          values: %w[running success failed canceled]
+      end
+      put ':id/deployments/:deployment_id' do
+        authorize!(:read_deployment, user_project)
+
+        deployment = user_project.deployments.find(params[:deployment_id])
+
+        authorize!(:update_deployment, deployment)
+
+        if deployment.deployable
+          forbidden!('Deployments created using GitLab CI can not be updated using the API')
+        end
+
+        service = ::Deployments::UpdateService.new(deployment, declared_params)
+
+        if service.execute
+          present(deployment, with: Entities::Deployment, current_user: current_user)
+        else
+          render_validation_error!(deployment)
+        end
+      end
     end
   end
 end

lib/gitlab/cycle_analytics/summary/deploy.rb

@@ -12,7 +12,7 @@ module Gitlab
 
         def value
           strong_memoize(:value) do
-            query = @project.deployments.where("created_at >= ?", @from)
+            query = @project.deployments.success.where("created_at >= ?", @from)
             query = query.where("created_at <= ?", @to) if @to
             query.count
           end

locale/gitlab.pot

@@ -5409,6 +5409,27 @@ msgstr ""
 msgid "Deploying to"
 msgstr ""
 
+msgid "Deployment|API"
+msgstr ""
+
+msgid "Deployment|This deployment was created using the API"
+msgstr ""
+
+msgid "Deployment|canceled"
+msgstr ""
+
+msgid "Deployment|created"
+msgstr ""
+
+msgid "Deployment|failed"
+msgstr ""
+
+msgid "Deployment|running"
+msgstr ""
+
+msgid "Deployment|success"
+msgstr ""
+
 msgid "Deprioritize label"
 msgstr ""
 

spec/controllers/projects/deployments_controller_spec.rb

@@ -75,15 +75,13 @@ describe Projects::DeploymentsController do
           }
         end
 
-        before do
+        it 'returns a metrics JSON document' do
           expect_next_instance_of(DeploymentMetrics) do |deployment_metrics|
             allow(deployment_metrics).to receive(:has_metrics?).and_return(true)
 
             expect(deployment_metrics).to receive(:metrics).and_return(empty_metrics)
           end
-        end
 
-        it 'returns a metrics JSON document' do
           get :metrics, params: deployment_params(id: deployment.to_param)
 
           expect(response).to be_ok
@@ -91,6 +89,19 @@ describe Projects::DeploymentsController do
           expect(json_response['metrics']).to eq({})
           expect(json_response['last_update']).to eq(42)
         end
+
+        it 'returns a 404 if the deployment failed' do
+          failed_deployment = create(
+            :deployment,
+            :failed,
+            project: project,
+            environment: environment
+          )
+
+          get :metrics, params: deployment_params(id: failed_deployment.to_param)
+
+          expect(response).to have_gitlab_http_status(404)
+        end
       end
     end
   end

spec/features/projects/environments/environment_spec.rb

@@ -66,8 +66,8 @@ describe 'Environment' do
           create(:deployment, :running, environment: environment, deployable: build)
         end
 
-        it 'does not show deployments' do
-          expect(page).to have_content('You don\'t have any deployments right now.')
+        it 'does show deployments' do
+          expect(page).to have_link("#{build.name} (##{build.id})")
         end
       end
 
@@ -79,8 +79,8 @@ describe 'Environment' do
           create(:deployment, :failed, environment: environment, deployable: build)
         end
 
-        it 'does not show deployments' do
-          expect(page).to have_content('You don\'t have any deployments right now.')
+        it 'does show deployments' do
+          expect(page).to have_link("#{build.name} (##{build.id})")
         end
       end
 

spec/fixtures/api/schemas/deployment.json

@@ -61,7 +61,7 @@
       "type": "array",
       "items": { "$ref": "job/job.json" }
     },
-    "status": { "type": "string" }		
+    "status": { "type": "string" }
   },
   "additionalProperties": false
 }

spec/helpers/environment_helper_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe EnvironmentHelper do
+  describe '#render_deployment_status' do
+    context 'when using a manual deployment' do
+      it 'renders a span tag' do
+        deploy = build(:deployment, deployable: nil, status: :success)
+        html = helper.render_deployment_status(deploy)
+
+        expect(html).to have_css('span.ci-status.ci-success')
+      end
+    end
+
+    context 'when using a deployment from a build' do
+      it 'renders a link tag' do
+        deploy = build(:deployment, status: :success)
+        html = helper.render_deployment_status(deploy)
+
+        expect(html).to have_css('a.ci-status.ci-success')
+      end
+    end
+  end
+end

spec/models/deployment_spec.rb

@@ -348,4 +348,17 @@ describe Deployment do
       expect(deployment.deployed_by).to eq(build_user)
     end
   end
+
+  describe '.find_successful_deployment!' do
+    it 'returns a successful deployment' do
+      deploy = create(:deployment, :success)
+
+      expect(described_class.find_successful_deployment!(deploy.iid)).to eq(deploy)
+    end
+
+    it 'raises when no deployment is found' do
+      expect { described_class.find_successful_deployment!(-1) }
+        .to raise_error(ActiveRecord::RecordNotFound)
+    end
+  end
 end

spec/models/environment_spec.rb

@@ -882,4 +882,19 @@ describe Environment, :use_clean_rails_memory_store_caching do
       end
     end
   end
+
+  describe '.find_or_create_by_name' do
+    it 'finds an existing environment if it exists' do
+      env = create(:environment)
+
+      expect(described_class.find_or_create_by_name(env.name)).to eq(env)
+    end
+
+    it 'creates an environment if it does not exist' do
+      env = project.environments.find_or_create_by_name('kittens')
+
+      expect(env).to be_an_instance_of(described_class)
+      expect(env).to be_persisted
+    end
+  end
 end

spec/policies/project_policy_spec.rb

@@ -40,14 +40,14 @@ describe ProjectPolicy do
       update_commit_status create_build update_build create_pipeline
       update_pipeline create_merge_request_from create_wiki push_code
       resolve_note create_container_image update_container_image destroy_container_image
-      create_environment create_deployment create_release update_release
+      create_environment create_deployment update_deployment create_release update_release
     ]
   end
 
   let(:base_maintainer_permissions) do
     %i[
       push_to_delete_protected_branch update_project_snippet update_environment
-      update_deployment admin_project_snippet admin_project_member admin_note admin_wiki admin_project
+      admin_project_snippet admin_project_member admin_note admin_wiki admin_project
       admin_commit_status admin_build admin_container_image
       admin_pipeline admin_environment admin_deployment destroy_release add_cluster
       daily_statistics

spec/requests/api/deployments_spec.rb

+# frozen_string_literal: true
+
 require 'spec_helper'
 
 describe API::Deployments do
@@ -96,4 +98,164 @@ describe API::Deployments do
       end
     end
   end
+
+  describe 'POST /projects/:id/deployments' do
+    let!(:project) { create(:project, :repository) }
+    let(:sha) { 'b83d6e391c22777fca1ed3012fce84f633d7fed0' }
+
+    context 'as a maintainer' do
+      it 'creates a new deployment' do
+        post(
+          api("/projects/#{project.id}/deployments", user),
+          params: {
+            environment: 'production',
+            sha: sha,
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(201)
+
+        expect(json_response['sha']).to eq(sha)
+        expect(json_response['ref']).to eq('master')
+        expect(json_response['environment']['name']).to eq('production')
+      end
+
+      it 'errors when creating a deployment with an invalid name' do
+        post(
+          api("/projects/#{project.id}/deployments", user),
+          params: {
+            environment: 'a' * 300,
+            sha: sha,
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(500)
+      end
+    end
+
+    context 'as a developer' do
+      it 'creates a new deployment' do
+        developer = create(:user)
+
+        project.add_developer(developer)
+
+        post(
+          api("/projects/#{project.id}/deployments", developer),
+          params: {
+            environment: 'production',
+            sha: sha,
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(201)
+
+        expect(json_response['sha']).to eq(sha)
+        expect(json_response['ref']).to eq('master')
+      end
+    end
+
+    context 'as non member' do
+      it 'returns a 404 status code' do
+        post(
+          api( "/projects/#{project.id}/deployments", non_member),
+          params: {
+            environment: 'production',
+            sha: '123',
+            ref: 'master',
+            tag: false,
+            status: 'success'
+          }
+        )
+
+        expect(response).to have_gitlab_http_status(404)
+      end
+    end
+  end
+
+  describe 'PUT /projects/:id/deployments/:deployment_id' do
+    let(:project) { create(:project) }
+    let(:build) { create(:ci_build, :failed, project: project) }
+    let(:environment) { create(:environment, project: project) }
+    let(:deploy) do
+      create(
+        :deployment,
+        :failed,
+        project: project,
+        environment: environment,
+        deployable: nil
+      )
+    end
+
+    context 'as a maintainer' do
+      it 'returns a 403 when updating a deployment with a build' do
+        deploy.update(deployable: build)
+
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", user),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(403)
+      end
+
+      it 'updates a deployment without an associated build' do
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", user),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(200)
+        expect(json_response['status']).to eq('success')
+      end
+    end
+
+    context 'as a developer' do
+      let(:developer) { create(:user) }
+
+      before do
+        project.add_developer(developer)
+      end
+
+      it 'returns a 403 when updating a deployment with a build' do
+        deploy.update(deployable: build)
+
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", developer),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(403)
+      end
+
+      it 'updates a deployment without an associated build' do
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", developer),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(200)
+        expect(json_response['status']).to eq('success')
+      end
+    end
+
+    context 'as non member' do
+      it 'returns a 404 status code' do
+        put(
+          api("/projects/#{project.id}/deployments/#{deploy.id}", non_member),
+          params: { status: 'success' }
+        )
+
+        expect(response).to have_gitlab_http_status(404)
+      end
+    end
+  end
 end

spec/services/update_deployment_service_spec.rb → spec/services/deployments/after_create_service_spec.rb

@@ -2,7 +2,7 @@
 
 require 'spec_helper'
 
-describe UpdateDeploymentService do
+describe Deployments::AfterCreateService do
   let(:user) { create(:user) }
   let(:project) { create(:project, :repository) }
   let(:options) { { name: 'production' } }

spec/services/deployments/create_service_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Deployments::CreateService do
+  let(:environment) do
+    double(
+      :environment,
+      deployment_platform: double(:platform, cluster_id: 1),
+      project_id: 2,
+      id: 3
+    )
+  end
+
+  let(:user) { double(:user) }
+
+  describe '#execute' do
+    let(:service) { described_class.new(environment, user, {}) }
+
+    it 'does not run the AfterCreateService service if the deployment is not persisted' do
+      deploy = double(:deployment, persisted?: false)
+
+      expect(service)
+        .to receive(:create_deployment)
+        .and_return(deploy)
+
+      expect(Deployments::AfterCreateService)
+        .not_to receive(:new)
+
+      expect(service.execute).to eq(deploy)
+    end
+
+    it 'runs the AfterCreateService service if the deployment is persisted' do
+      deploy = double(:deployment, persisted?: true)
+      after_service = double(:after_create_service)
+
+      expect(service)
+        .to receive(:create_deployment)
+        .and_return(deploy)
+
+      expect(Deployments::AfterCreateService)
+        .to receive(:new)
+        .with(deploy)
+        .and_return(after_service)
+
+      expect(after_service)
+        .to receive(:execute)
+
+      expect(service.execute).to eq(deploy)
+    end
+  end
+
+  describe '#create_deployment' do
+    it 'creates a deployment' do
+      environment = build(:environment)
+      service = described_class.new(environment, user, {})
+
+      expect(environment.deployments)
+        .to receive(:create)
+        .with(an_instance_of(Hash))
+
+      service.create_deployment
+    end
+  end
+
+  describe '#deployment_attributes' do
+    it 'only includes attributes that we want to persist' do
+      service = described_class.new(
+        environment,
+        user,
+        ref: 'master',
+        tag: true,
+        sha: '123',
+        foo: 'bar',
+        on_stop: 'stop',
+        status: 'running'
+      )
+
+      expect(service.deployment_attributes).to eq(
+        cluster_id: 1,
+        project_id: 2,
+        environment_id: 3,
+        ref: 'master',
+        tag: true,
+        sha: '123',
+        user: user,
+        on_stop: 'stop',
+        status: 'running'
+      )
+    end
+  end
+end

spec/services/deployments/update_service_spec.rb

+# frozen_string_literal: true
+
+require 'spec_helper'
+
+describe Deployments::UpdateService do
+  let(:deploy) { create(:deployment, :running) }
+  let(:service) { described_class.new(deploy, status: 'success') }
+
+  describe '#execute' do
+    it 'updates the status of a deployment' do
+      expect(service.execute).to eq(true)
+      expect(deploy.status).to eq('success')
+    end
+  end
+end

spec/support/shared_contexts/policies/project_policy_shared_context.rb

@@ -38,14 +38,14 @@ RSpec.shared_context 'ProjectPolicy context' do
       update_commit_status create_build update_build create_pipeline
       update_pipeline create_merge_request_from create_wiki push_code
       resolve_note create_container_image update_container_image
-      create_environment create_deployment create_release update_release
+      create_environment create_deployment update_deployment create_release update_release
     ]
   end
 
   let(:base_maintainer_permissions) do
     %i[
       push_to_delete_protected_branch update_project_snippet update_environment
-      update_deployment admin_project_snippet admin_project_member admin_note admin_wiki admin_project
+      admin_project_snippet admin_project_member admin_note admin_wiki admin_project
       admin_commit_status admin_build admin_container_image
       admin_pipeline admin_environment admin_deployment destroy_release add_cluster
       daily_statistics

spec/workers/deployments/success_worker_spec.rb

@@ -8,8 +8,8 @@ describe Deployments::SuccessWorker do
   context 'when successful deployment' do
     let(:deployment) { create(:deployment, :success) }
 
-    it 'executes UpdateDeploymentService' do
-      expect(UpdateDeploymentService)
+    it 'executes Deployments::AfterCreateService' do
+      expect(Deployments::AfterCreateService)
         .to receive(:new).with(deployment).and_call_original
 
       subject
@@ -19,8 +19,8 @@ describe Deployments::SuccessWorker do
   context 'when canceled deployment' do
     let(:deployment) { create(:deployment, :canceled) }
 
-    it 'does not execute UpdateDeploymentService' do
-      expect(UpdateDeploymentService).not_to receive(:new)
+    it 'does not execute Deployments::AfterCreateService' do
+      expect(Deployments::AfterCreateService).not_to receive(:new)
 
       subject
     end
@@ -29,8 +29,8 @@ describe Deployments::SuccessWorker do
   context 'when deploy record does not exist' do
     let(:deployment) { nil }
 
-    it 'does not execute UpdateDeploymentService' do
-      expect(UpdateDeploymentService).not_to receive(:new)
+    it 'does not execute Deployments::AfterCreateService' do
+      expect(Deployments::AfterCreateService).not_to receive(:new)
 
       subject
     end