2017-02-03 13:41:35 -05:00
# Slack Notifications Service
2017-04-28 05:47:59 -04:00
The Slack Notifications Service allows your GitLab project to send events (e.g. issue created) to your existing Slack team as notifications. This requires configurations in both Slack and GitLab.
2017-02-03 13:41:35 -05:00
2017-04-28 05:47:59 -04:00
> Note: You can also use Slack slash commands to control GitLab inside Slack. This is the separately configured [Slack slash commands](slack_slash_commands.md).
2017-02-03 13:41:35 -05:00
2017-04-28 05:47:59 -04:00
## Slack Configuration
2017-02-03 13:41:35 -05:00
2019-07-08 19:14:29 -04:00
1. Sign in to your Slack team and [start a new Incoming WebHooks configuration ](https://my.slack.com/services/new/incoming-webhook ).
2017-04-28 05:47:59 -04:00
1. Select the Slack channel where notifications will be sent to by default. Click the **Add Incoming WebHooks integration** button to add the configuration.
1. Copy the **Webhook URL** , which we'll use later in the GitLab configuration.
2017-02-03 13:41:35 -05:00
2017-04-28 05:47:59 -04:00
## GitLab Configuration
2017-02-03 13:41:35 -05:00
2020-03-30 17:08:01 -04:00
1. Navigate to the [Integrations page ](overview.md#accessing-integrations ) in your project's settings, i.e. **Project > Settings > Integrations** .
1. Select the **Slack notifications** integration to configure it.
2017-04-28 05:47:59 -04:00
1. Check the **Active** checkbox to turn on the service.
1. Check the checkboxes corresponding to the GitLab events you want to send to Slack as a notification.
2020-02-25 16:09:23 -05:00
1. For each event, optionally enter the Slack channel names where you want to send the event, separated by a comma. If left empty, the event will be sent to the default channel that you configured in the Slack Configuration step. **Note:** Usernames and private channels are not supported. To send direct messages, use the Member ID found under user's Slack profile.
2017-04-28 05:47:59 -04:00
1. Paste the **Webhook URL** that you copied from the Slack Configuration step.
1. Optionally customize the Slack bot username that will be sending the notifications.
1. Configure the remaining options and click `Save changes` .
2017-02-03 13:41:35 -05:00
2017-04-28 05:47:59 -04:00
Your Slack team will now start receiving GitLab event notifications as configured.
2017-02-03 13:41:35 -05:00
2019-01-11 20:28:23 -05:00
![Slack configuration ](img/slack_configuration.png )
## Troubleshooting
If you're having trouble with the Slack integration not working, then start by
2019-01-23 11:13:01 -05:00
searching through the [Sidekiq logs ](../../../administration/logs.md#sidekiqlog )
2019-01-14 17:11:11 -05:00
for errors relating to your Slack service.
2019-01-11 20:28:23 -05:00
### Something went wrong on our end
This is a generic error shown in the GitLab UI and doesn't mean much by itself.
2019-01-23 11:13:01 -05:00
You'll need to look in [the logs ](../../../administration/logs.md#productionlog ) to find
2019-01-22 12:52:43 -05:00
an error message and keep troubleshooting from there.
2019-01-11 20:28:23 -05:00
2019-01-14 17:11:11 -05:00
### `certificate verify failed`
You may see an entry similar to the following in your Sidekiq log:
```text
2019-01-10_13:22:08.42572 2019-01-10T13:22:08.425Z 6877 TID-abcdefg ProjectServiceWorker JID-3bade5fb3dd47a85db6d78c5 ERROR: {:class=>"ProjectServiceWorker", :service_class=>"SlackService", :message=>"SSL_connect returned=1 errno=0 state=error: certificate verify failed"}
```
2019-01-11 20:28:23 -05:00
This is probably a problem either with GitLab communicating with Slack, or GitLab
communicating with itself. The former is less likely since Slack's security certificates
should _hopefully_ always be trusted. We can establish which we're dealing with by using
2019-01-22 14:39:51 -05:00
the below rails console script.
2019-01-11 20:28:23 -05:00
2020-01-30 10:09:15 -05:00
```shell
2019-01-22 14:39:51 -05:00
# start a rails console:
2020-02-28 01:09:19 -05:00
sudo gitlab-rails console -e production
2019-01-22 14:39:51 -05:00
# or for source installs:
2020-02-28 01:09:19 -05:00
bundle exec rails console -e production
2019-01-22 14:39:51 -05:00
```
2019-01-11 20:28:23 -05:00
2019-01-22 14:39:51 -05:00
```ruby
# run this in the Rails console
2019-01-11 20:28:23 -05:00
# replace <SLACK URL> with your actual Slack URL
2019-01-22 14:39:51 -05:00
result = Net::HTTP.get(URI('https://< SLACK URL > '));0
2019-01-11 20:28:23 -05:00
# replace <GITLAB URL> with your actual GitLab URL
2019-01-22 14:39:51 -05:00
result = Net::HTTP.get(URI('https://< GITLAB URL > '));0
2019-01-11 20:28:23 -05:00
```
2019-01-14 17:11:11 -05:00
If it's an issue with GitLab not trusting HTTPS connections to itself, then you may simply
need to [add your certificate to GitLab's trusted certificates ](https://docs.gitlab.com/omnibus/settings/ssl.html#install-custom-public-certificates ).
2019-01-11 20:28:23 -05:00
If it's an issue with GitLab not trusting connections to Slack, then the GitLab
OpenSSL trust store probably got messed up somehow. Typically this is from overriding
the trust store with `gitlab_rails['env'] = {"SSL_CERT_FILE" => "/path/to/file.pem"}`
2019-01-23 11:13:01 -05:00
or by accidentally modifying the default CA bundle `/opt/gitlab/embedded/ssl/certs/cacert.pem` .