A step-by-step guide to setting up GitLab notifications in your Slack workspace
The GitLab notifications integration enables you to receive all the updates/changes happening in your GitLab repositories directly in Slack where everyone concerned can see them, without jumping between tools.
In this tutorial, we’ll give you a step-by-step guide to how you can set up this Slack notification integration from GitLab.
What you’ll need
To follow along with this tutorial, you’ll need the following:
Write access to a GitLab project
Admin access to a Slack workspace
Installing a new Slack app
The first step in setting up this integration is to create a new Slack app.
Visit api.slack.com/apps and sign in if you’re not signed in already.
Select From Scratch from the modal that appears.
Give the app a name and choose the Slack workspace you want to link the app with. To keep things simple, just call it GitLab.
On the next page, click on the Incoming Webhook tile under the Add features and functionality section.
On the Incoming Webhook page, turn on the Activate incoming webhook toggle.
A new section will appear. Click Add New Webhook to Workspace towards the bottom of the section.
You’ll be asked to give your new app access to your workspace. Click Allow.
Copy the newly generated webhook URL and paste it somewhere. We’ll use it in a later step.
With these steps, we’ve exposed an API endpoint to the outside world which can be used by other applications to send messages to our Slack workspace. Next, we’ll configure GitLab to use this API endpoint to send us messages about our repository.
Configuring Slack notifications on GitLab
To configure the integration on the GitLab side, follow these steps:
Open your GitLab project by going to the GitLab homepage and selecting your project from the list. Alternatively, you can arrive at the same projects page by selecting Menu > Projects > Your Projects in the top left corner of the GitLab app.
While on the project page, select Settings > Integration
Select Slack notifications from the Add an Integration list.
Inside the configuration page that opens, check the Active checkbox in the Enable integration section.
Scroll down to the Webhook section, and paste in the Webhook URL you copied when configuring Slack. If you forgot to copy the URL, you can find it by visiting <yourteamname>.slack.com/app and then selecting Manage > Custom Integrations.
Optionally, you can customize the name of the Slack bot that sends messages about the GitLab project by providing it a username.
To test if the settings are correct, simply click the Test setting button. You’ll receive a Slack message from the GitLab bot listing the recent activity in your project.
If the settings are correct, save them by clicking the Save Settings button.
Congratulations! You’ve now configured your GitLabs project to send Slack messages about changes to your repository.
Note that the same Slack Webhook URL can be used to send messages from more than one GitLab repository. If you want to set up another repository to send you messages on Slack, follow the same process listed above from another project.
Customizing messages and channels
You can also customize which events trigger a message, as well as which Slack channels those messages are sent to.
Subscribe/Unsubscribe to repository events
By default, the GitLab Slack notification integration will send a message about almost every activity on your repository, including pushes, merge requests, pipeline changes, etc. If you want to unsubscribe to some of these events and subscribe to others that are not sent by default, you can:
Visit your project page and select Settings > Integrations from the left side menu.
In the Active integrations section, select Slack notifications.
The Trigger section of the integration page has checkboxes for all kinds of events that trigger a message. You can subscribe unsubscribe to repository events by selecting/deselecting these checkboxes.
You can also use the text input below the checkboxes to specify which channels a particular message type should be sent to. The channels can be specified using a comma-separated list in the same format as the placeholder text.
You’re now set up to receive a customized set of messages from your GitLab projects right inside your Slack workspace. However, the flow of information in this integration is very one-sided. That is, GitLab gets to choose when to send a message in case an update happens. What if you wanted to query your GitLab project about information or issue a command like opening or closing an issue? Fortunately, GitLabs provides an integration for that use-case as well. This integration uses the new API called Slack Apps and is very easy to set up. Adding this integration will allow you to use a command line-like interface called Slack slash commands to query and issues commands to your GitLab project. You can follow this tutorial to configure it.