Merge branch 'feat/circuit-project-service' into 'master'

Add Unify Circuit project integration service

See merge request gitlab-org/gitlab!19849

app/models/project.rb

@@ -170,6 +170,7 @@ class Project < ApplicationRecord
   has_one :microsoft_teams_service
   has_one :packagist_service
   has_one :hangouts_chat_service
+  has_one :unify_circuit_service
 
   has_one :root_of_fork_network,
           foreign_key: 'root_project_id',

app/models/project_services/unify_circuit_service.rb

+# frozen_string_literal: true
+
+class UnifyCircuitService < ChatNotificationService
+  def title
+    'Unify Circuit'
+  end
+
+  def description
+    'Receive event notifications in Unify Circuit'
+  end
+
+  def self.to_param
+    'unify_circuit'
+  end
+
+  def help
+    'This service sends notifications about projects events to a Unify Circuit conversation.<br />
+    To set up this service:
+    <ol>
+      <li><a href="https://www.circuit.com/unifyportalfaqdetail?articleId=164448">Set up an incoming webhook for your conversation</a>. All notifications will come to this conversation.</li>
+      <li>Paste the <strong>Webhook URL</strong> into the field below.</li>
+      <li>Select events below to enable notifications.</li>
+    </ol>'
+  end
+
+  def event_field(event)
+  end
+
+  def default_channel_placeholder
+  end
+
+  def self.supported_events
+    %w[push issue confidential_issue merge_request note confidential_note tag_push
+       pipeline wiki_page]
+  end
+
+  def default_fields
+    [
+      { type: 'text', name: 'webhook', placeholder: "e.g. https://circuit.com/rest/v2/webhooks/incoming/…", required: true },
+      { type: 'checkbox', name: 'notify_only_broken_pipelines' },
+      { type: 'select', name: 'branches_to_be_notified', choices: BRANCH_CHOICES }
+    ]
+  end
+
+  private
+
+  def notify(message, opts)
+    response = Gitlab::HTTP.post(webhook, body: {
+      subject: message.project_name,
+      text: message.pretext,
+      markdown: true
+    }.to_json)
+
+    response if response.success?
+  end
+
+  def custom_data(data)
+    super(data).merge(markdown: true)
+  end
+end

app/models/service.rb

@@ -289,6 +289,7 @@ class Service < ApplicationRecord
       slack
       teamcity
       microsoft_teams
+      unify_circuit
     ]
 
     if Rails.env.development?

changelogs/unreleased/feat-circuit-project-service.yml

+---
+title: Add Unify Circuit project integration service
+merge_request: 19849
+author: Fabio Huser
+type: added

doc/api/services.md

@@ -229,6 +229,51 @@ Get Campfire service settings for a project.
 GET /projects/:id/services/campfire
 ```
 
+## Unify Circuit
+
+Unify Circuit RTC and collaboration tool.
+
+### Create/Edit Unify Circuit service
+
+Set Unify Circuit service for a project.
+
+```
+PUT /projects/:id/services/unify-circuit
+```
+
+Parameters:
+
+| Parameter | Type | Required | Description |
+| --------- | ---- | -------- | ----------- |
+| `webhook` | string | true | The Unify Circuit webhook. For example, `https://circuit.com/rest/v2/webhooks/incoming/...`. |
+| `notify_only_broken_pipelines` | boolean | false | Send notifications for broken pipelines |
+| `branches_to_be_notified` | string | all | Branches to send notifications for. Valid options are "all", "default", "protected", and "default_and_protected" |
+| `push_events` | boolean | false | Enable notifications for push events |
+| `issues_events` | boolean | false | Enable notifications for issue events |
+| `confidential_issues_events` | boolean | false | Enable notifications for confidential issue events |
+| `merge_requests_events` | boolean | false | Enable notifications for merge request events |
+| `tag_push_events` | boolean | false | Enable notifications for tag push events |
+| `note_events` | boolean | false | Enable notifications for note events |
+| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
+| `pipeline_events` | boolean | false | Enable notifications for pipeline events |
+| `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
+
+### Delete Unify Circuit service
+
+Delete Unify Circuit service for a project.
+
+```
+DELETE /projects/:id/services/unify-circuit
+```
+
+### Get Unify Circuit service settings
+
+Get Unify Circuit service settings for a project.
+
+```
+GET /projects/:id/services/unify-circuit
+```
+
 ## Custom Issue Tracker
 
 Custom issue tracker
@@ -480,6 +525,7 @@ Parameters:
 | `merge_requests_events` | boolean | false | Enable notifications for merge request events |
 | `tag_push_events` | boolean | false | Enable notifications for tag push events |
 | `note_events` | boolean | false | Enable notifications for note events |
+| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
 | `pipeline_events` | boolean | false | Enable notifications for pipeline events |
 | `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
 
@@ -1088,6 +1134,7 @@ Parameters:
 | `merge_requests_events` | boolean | false | Enable notifications for merge request events |
 | `tag_push_events` | boolean | false | Enable notifications for tag push events |
 | `note_events` | boolean | false | Enable notifications for note events |
+| `confidential_note_events` | boolean | false | Enable notifications for confidential note events |
 | `pipeline_events` | boolean | false | Enable notifications for pipeline events |
 | `wiki_page_events` | boolean | false | Enable notifications for wiki page events |
 | `push_channel` | string | false | The name of the channel to receive push events notifications |
@@ -1095,6 +1142,7 @@ Parameters:
 | `confidential_issue_channel` | string | false | The name of the channel to receive confidential issues events notifications |
 | `merge_request_channel` | string | false | The name of the channel to receive merge request events notifications |
 | `note_channel` | string | false | The name of the channel to receive note events notifications |
+| `confidential_note_channel` | boolean | The name of the channel to receive confidential note events notifications |
 | `tag_push_channel` | string | false | The name of the channel to receive tag push events notifications |
 | `pipeline_channel` | string | false | The name of the channel to receive pipeline events notifications |
 | `wiki_page_channel` | string | false | The name of the channel to receive wiki page events notifications |

doc/user/project/integrations/project_services.md

@@ -54,6 +54,7 @@ Click on the service links to see further configuration instructions and details
 | [Prometheus](prometheus.md) | Monitor the performance of your deployed apps |
 | Pushover | Pushover makes it easy to get real-time notifications on your Android device, iPhone, iPad, and Desktop |
 | [Redmine](redmine.md) | Redmine issue tracker |
+| [Unify Circuit](unify_circuit.md) | Receive events notifications in Unify Circuit |
 | [YouTrack](youtrack.md) | YouTrack issue tracker |
 
 ## Push hooks limit

doc/user/project/integrations/unify_circuit.md

+# Unify Circuit service
+
+The Unify Circuit service sends notifications from GitLab to the conversation for which the webhook was created.
+
+## On Unify Circuit
+
+1. Open the conversation in which you want to see the notifications.
+1. From the conversation menu, select **Configure Webhooks**.
+1. Click **ADD WEBHOOK** and fill in the name of the bot that will post the messages. Optionally define avatar.
+1. Click **SAVE** and copy the **Webhook URL** of your webhook.
+
+For more information, see the [Unify Circuit documentation for configuring incoming webhooks](https://www.circuit.com/unifyportalfaqdetail?articleId=164448).
+
+## On GitLab
+
+When you have the **Webhook URL** for your Unify Circuit conversation webhook, you can set up the GitLab service.
+
+1. Navigate to the [Integrations page](project_services.md#accessing-the-project-services) in your project's settings, i.e. **Project > Settings > Integrations**.
+1. Select the **Unify Circuit** project service to configure it.
+1. Check the **Active** checkbox to turn on the service.
+1. Check the checkboxes corresponding to the GitLab events you want to receive in Unify Circuit.
+1. Paste the **Webhook URL** that you copied from the Unify Circuit configuration step.
+1. Configure the remaining options and click `Save changes`.
+
+Your Unify Circuit conversation will now start receiving GitLab event notifications as configured.
+
+![Unify Circuit configuration](img/unify_circuit_configuration.png)

lib/api/helpers/services_helpers.rb

@@ -132,6 +132,12 @@ module API
             type: Boolean,
             desc: 'Enable notifications for note_events'
           },
+          {
+            required: false,
+            name: :confidential_note_events,
+            type: Boolean,
+            desc: 'Enable notifications for confidential_note_events'
+          },
           {
             required: false,
             name: :tag_push_events,
@@ -696,7 +702,16 @@ module API
               type: String,
               desc: 'The password of the user'
             }
-          ]
+          ],
+          'unify-circuit' => [
+            {
+              required: true,
+              name: :webhook,
+              type: String,
+              desc: 'The Unify Circuit webhook. e.g. https://circuit.com/rest/v2/webhooks/incoming/…'
+            },
+            chat_notification_events
+          ].flatten
         }
       end
 

spec/lib/gitlab/import_export/all_models.yml

@@ -290,6 +290,7 @@ project:
 - microsoft_teams_service
 - mattermost_service
 - hangouts_chat_service
+- unify_circuit_service
 - buildkite_service
 - bamboo_service
 - teamcity_service

spec/models/project_services/unify_circuit_service_spec.rb

+# frozen_string_literal: true
+
+require "spec_helper"
+
+describe UnifyCircuitService do
+  it_behaves_like "chat service", "Unify Circuit" do
+    let(:client_arguments) { webhook_url }
+    let(:content_key) { :subject }
+  end
+end

spec/models/project_spec.rb

@@ -33,6 +33,7 @@ describe Project do
     it { is_expected.to have_one(:microsoft_teams_service) }
     it { is_expected.to have_one(:mattermost_service) }
     it { is_expected.to have_one(:hangouts_chat_service) }
+    it { is_expected.to have_one(:unify_circuit_service) }
     it { is_expected.to have_one(:packagist_service) }
     it { is_expected.to have_one(:pushover_service) }
     it { is_expected.to have_one(:asana_service) }

spec/support/shared_examples/models/chat_service_shared_examples.rb

@@ -80,7 +80,7 @@ shared_examples_for "chat service" do |service_name|
 
       it_behaves_like "triggered #{service_name} service"
 
-      it "specifies the webhook when it is configured" do
+      it "specifies the webhook when it is configured", if: defined?(client) do
         expect(client).to receive(:new).with(client_arguments).and_return(double(:chat_service).as_null_object)
 
         subject.execute(sample_data)