debian-mirror-gitlab/doc/user/project/integrations/slack.md

148 lines
7.4 KiB
Markdown
Raw Normal View History

2020-10-24 23:57:45 +05:30
---
2022-11-25 23:54:43 +05:30
stage: Manage
2021-10-27 15:23:28 +05:30
group: Integrations
2022-11-25 23:54:43 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/product/ux/technical-writing/#assignments
2020-10-24 23:57:45 +05:30
---
2021-10-27 15:23:28 +05:30
# Slack notifications service **(FREE)**
2017-08-17 22:00:37 +05:30
2021-10-27 15:23:28 +05:30
The Slack notifications service enables your GitLab project to send events
2020-07-28 23:09:34 +05:30
(such as issue creation) to your existing Slack team as notifications. Setting up
Slack notifications requires configuration changes for both Slack and GitLab.
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
You can also use [Slack slash commands](slack_slash_commands.md)
to control GitLab from Slack. Slash commands are configured separately.
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
## Configure Slack
2017-08-17 22:00:37 +05:30
2019-09-30 21:07:59 +05:30
1. Sign in to your Slack team and [start a new Incoming WebHooks configuration](https://my.slack.com/services/new/incoming-webhook).
2021-10-27 15:23:28 +05:30
1. Identify the Slack channel where notifications should be sent to by default.
Select **Add Incoming WebHooks integration** to add the configuration.
2021-11-11 11:23:49 +05:30
1. Copy the **Webhook URL** to use later when you configure GitLab.
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
## Configure GitLab
2017-08-17 22:00:37 +05:30
2022-10-11 01:57:18 +05:30
1. On the top bar, select **Main menu > Projects** and find your project.
2021-10-27 15:23:28 +05:30
1. On the left sidebar, select **Settings > Integrations**.
2021-11-11 11:23:49 +05:30
1. Select **Slack notifications**.
2021-10-27 15:23:28 +05:30
1. In the **Enable integration** section, select the **Active** checkbox.
1. In the **Trigger** section, select the checkboxes for each type of GitLab
event to send to Slack as a notification. For a full list, see
2021-11-11 11:23:49 +05:30
[Triggers for Slack notifications](#triggers-for-slack-notifications).
2021-10-27 15:23:28 +05:30
By default, messages are sent to the channel you configured during
2021-11-11 11:23:49 +05:30
[Slack configuration](#configure-slack).
2022-01-26 12:08:38 +05:30
1. Optional. To send messages to a different channel, multiple channels, or as
2021-10-27 15:23:28 +05:30
a direct message:
- *To send messages to channels,* enter the Slack channel names, separated by
commas.
- *To send direct messages,* use the Member ID found in the user's Slack profile.
2020-07-28 23:09:34 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2020-07-28 23:09:34 +05:30
Usernames and private channels are not supported.
2021-11-11 11:23:49 +05:30
1. In **Webhook**, enter the webhook URL you copied in the
[Slack configuration](#configure-slack) step.
2022-01-26 12:08:38 +05:30
1. Optional. In **Username**, enter the username of the Slack bot that sends
2021-10-27 15:23:28 +05:30
the notifications.
1. Select the **Notify only broken pipelines** checkbox to notify only on failures.
2021-12-11 22:18:48 +05:30
1. In the **Branches for which notifications are to be sent** dropdown, select which types of branches
2020-07-28 23:09:34 +05:30
to send notifications for.
2021-11-11 11:23:49 +05:30
1. Leave the **Labels to be notified** field blank to get all notifications, or
add labels that the issue or merge request must have to trigger a
2021-10-27 15:23:28 +05:30
notification.
1. Select **Test settings** to verify your information, and then select
**Save changes**.
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
Your Slack team now starts receiving GitLab event notifications as configured.
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
## Triggers for Slack notifications
2020-06-23 00:09:42 +05:30
The following triggers are available for Slack notifications:
2022-03-02 08:16:31 +05:30
| Trigger name | Trigger event |
|--------------------------------------------------------------------------|------------------------------------------------------|
| **Push** | A push to the repository. |
| **Issue** | An issue is created, updated, or closed. |
| **Confidential issue** | A confidential issue is created, updated, or closed. |
| **Merge request** | A merge request is created, updated, or merged. |
| **Note** | A comment is added. |
| **Confidential note** | A confidential note is added. |
| **Tag push** | A new tag is pushed to the repository. |
| **Pipeline** | A pipeline status changed. |
| **Wiki page** | A wiki page is created or updated. |
| **Deployment** | A deployment starts or finishes. |
| **Alert** | A new, unique alert is recorded. |
| [**Vulnerability**](../../application_security/vulnerabilities/index.md) | A new, unique vulnerability is recorded. |
2019-03-02 22:35:43 +05:30
## Troubleshooting
2020-07-28 23:09:34 +05:30
If your Slack integration is not working, start troubleshooting by
2022-08-27 11:52:29 +05:30
searching through the [Sidekiq logs](../../../administration/logs/index.md#sidekiqlog)
2019-03-02 22:35:43 +05:30
for errors relating to your Slack service.
### Something went wrong on our end
2021-11-11 11:23:49 +05:30
You might get this generic error message in the GitLab UI.
2022-08-27 11:52:29 +05:30
Review [the logs](../../../administration/logs/index.md#productionlog) to find
2021-11-11 11:23:49 +05:30
the error message and keep troubleshooting from there.
2019-03-02 22:35:43 +05:30
### `certificate verify failed`
2021-11-11 11:23:49 +05:30
You might see an entry like the following in your Sidekiq log:
2019-03-02 22:35:43 +05:30
2020-05-24 23:13:21 +05:30
```plaintext
2022-07-23 23:45:48 +05:30
2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg Integrations::ExecuteWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"Integrations::ExecuteWorker :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"}
2019-03-02 22:35:43 +05:30
```
2021-11-11 11:23:49 +05:30
This issue occurs when there is a problem with GitLab communicating with Slack,
or GitLab communicating with itself.
The former is less likely, as Slack security certificates should always be trusted.
2019-03-02 22:35:43 +05:30
2021-11-11 11:23:49 +05:30
To view which of these problems is the cause of the issue:
2019-03-02 22:35:43 +05:30
2021-11-11 11:23:49 +05:30
1. Start a Rails console:
2019-03-02 22:35:43 +05:30
2021-11-11 11:23:49 +05:30
```shell
sudo gitlab-rails console -e production
2019-03-02 22:35:43 +05:30
2021-11-11 11:23:49 +05:30
# for source installs:
bundle exec rails console -e production
```
1. Run the following commands:
```ruby
# replace <SLACK URL> with your actual Slack URL
result = Net::HTTP.get(URI('https://<SLACK URL>'));0
# replace <GITLAB URL> with your actual GitLab URL
result = Net::HTTP.get(URI('https://<GITLAB URL>'));0
```
2019-03-02 22:35:43 +05:30
2021-11-11 11:23:49 +05:30
If GitLab does not trust HTTPS connections to itself,
[add your certificate to the GitLab trusted certificates](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates).
2019-03-02 22:35:43 +05:30
2021-11-11 11:23:49 +05:30
If GitLab does not trust connections to Slack,
the GitLab OpenSSL trust store is incorrect. Typical causes are:
2021-10-27 15:23:28 +05:30
- Overriding the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`.
- Accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem`.
2022-11-25 23:54:43 +05:30
### Bulk update to disable the Slack Notification service
To disable notifications for all projects that have Slack integration enabled,
[start a rails console session](../../../administration/operations/rails_console.md#starting-a-rails-console-session) and use a script similar to the following:
WARNING:
Any command that changes data directly could be damaging if not run correctly, or under the right conditions. We highly recommend running them in a test environment with a backup of the instance ready to be restored, just in case.
```ruby
# Grab all projects that have the Slack notifications enabled
p = Project.find_by_sql("SELECT p.id FROM projects p LEFT JOIN integrations s ON p.id = s.project_id WHERE s.type_new = 'Slack' AND s.active = true")
# Disable the service on each of the projects that were found.
p.each do |project|
project.slack_service.update!(:active, false)
end
```