GitLab + Mattermost Integration: Setup & Configuration Guide

The GitLab + Mattermost integration connects your team's project management with real-time chat. Notifications, slash commands, and CI/CD alerts flow directly into Mattermost channels, reducing context switching and keeping everyone in sync. Two integration approaches exist: the modern plugin-based method (recommended) and the deprecated Omnibus bundle (for legacy instances). This guide covers setup, troubleshooting, and when to use each approach.

What Is the GitLab + Mattermost Integration?

The integration bridges your GitLab project activity and Mattermost chat channels. When someone opens a merge request, commits code, or triggers a pipeline, Mattermost receives a notification. Team members can subscribe to specific project events, search GitLab issues from chat, and trigger actions using slash commands. The two-way flow means developers spend less time context-switching between tools.

Real-world use case: A DevSecOps team at a 40-person company uses the integration to route security scan failures (from GitLab CI/CD) directly into a #security-alerts Mattermost channel. On-call engineers see the alert immediately. They use /gitlab slash commands to reassign issues without leaving chat.

The integration supports these events: pushes, merge requests, issues, wiki pages, deployment notifications, and pipeline status. You control which events trigger notifications and which channel receives them. Channel subscriptions are managed at the project level, so different teams can subscribe to different projects without interference.

Critical: The Omnibus Bundle Is Deprecated

This is the biggest setup decision you'll make, and most outdated guides miss it.

For years, GitLab shipped Mattermost as part of its Omnibus installer. A single omnibus-gitlab package installed both tools together. That approach is gone.

Timeline:

• GitLab 18.9 (September 2024): Omnibus Mattermost was deprecated.
• GitLab 19.0 (January 2025): Omnibus Mattermost was removed entirely.

If you're running GitLab 18.8 or earlier with Mattermost bundled in, you are on the deprecated path. Your Mattermost instance is no longer receiving security updates or feature releases as part of GitLab's lifecycle.

Why this matters: Hundreds of teams still run old versions of GitLab with the bundled Mattermost. Most setup guides online are written for this deprecated flow, and they will not work on current GitLab releases. When you follow an old guide and hit errors, it is because the Omnibus bundle no longer exists.

If you're running the deprecated bundle, you have two options:

1. Upgrade GitLab to 19.0+, then migrate to the standalone plugin approach (recommended).
2. Keep the old Omnibus instance in place but know it won't receive updates.

Most teams choose option 1. This guide assumes you're doing that.

Two Integration Approaches: Plugin vs. Omnibus

The plugin-based integration is the modern standard. The Omnibus bundle is deprecated.

Use the plugin approach if you are setting up a new integration, running GitLab 19.0 or later, running self-hosted Mattermost of any version, running Mattermost Cloud or managed Mattermost.

Use the Omnibus bundle approach only if you are running GitLab 18.8 or earlier (and plan to stay there indefinitely) or migrating from an old Omnibus instance and want to preserve historical configuration.

If you're not 100% certain which path you're on, use the plugin approach. It is the future.

Step-by-Step: Installing the GitLab Plugin

Here is how to set up the plugin-based integration from scratch.

Step 1: Install the Plugin from Mattermost Marketplace

Log into your Mattermost instance with a System Admin account. Go to System Console > Integrations > App Market or navigate directly to the Marketplace tab in the web interface.

Search for "GitLab" in the app market. You'll see the official "GitLab" plugin by Mattermost. Click "Install" (or "Get Started" if it is not yet installed). The installer will prompt you to enable the plugin. Click "Enable" and wait for the confirmation screen.

If you're running a self-hosted Mattermost instance and the Marketplace is not available, you can install the plugin manually by downloading it from the GitHub repository. Teams using Mattermost Cloud skip this complexity entirely since the plugin comes pre-installed.

Step 2: Register an OAuth App in GitLab

The plugin needs OAuth credentials from GitLab to authenticate users.

If you're using GitLab.com (SaaS): Log into https://gitlab.com, go to your profile > Preferences > Applications, and create a new application named "Mattermost Integration." Set the redirect URI to your Mattermost domain with the path /plugins/com.github.mattermost.plugin-gitlab/complete/oauth. Check these scopes: read_api, read_user, read_repository, and write_repository. Copy the Application ID and Application Secret.

If you're using GitLab self-hosted: Log into your GitLab instance as an administrator, go to Admin Area > Applications, and create a new application with the same name, redirect URI path, and scopes. Use your GitLab domain instead of gitlab.com. Copy the Application ID and Application Secret.

Critical detail: The redirect URI must match exactly. A common mistake is using the wrong protocol (secure vs. insecure), or forgetting the trailing path. Copy it carefully.

Step 3: Configure the Plugin in Mattermost

Go back to your Mattermost instance and navigate to System Console > Integrations > GitLab (or search for "GitLab" in the System Console search bar). Paste the OAuth credentials: Application ID from GitLab, Application Secret from GitLab.

Set the GitLab URL. If you're using GitLab.com, leave this blank or set it to https://gitlab.com. If you're using self-hosted GitLab, enter your domain with the secure protocol (for example, your self-hosted GitLab server address).

Click "Save" and wait for the confirmation. The plugin is now configured. You'll know it worked when users see a "Connect to GitLab" button in Mattermost (either in the app menu or in their account settings).

Setting Up Notifications and Webhooks

With the plugin installed, you now need to configure webhooks to route GitLab events into Mattermost channels. This is the step where most teams get stuck if they're unfamiliar with webhook URLs and secrets. Understanding the true cost of self-hosted Mattermost, especially DevOps labor for webhook configuration, helps teams decide between self-hosted and managed approaches.

Create an Incoming Webhook in Mattermost

In Mattermost, go to your target channel (for example, #devops-alerts). Click the channel name > Integrations > Incoming Webhooks. Click "Add Incoming Webhook." Name it "GitLab Notifications" (or similar). Copy the webhook URL (it will be a unique URL assigned to that webhook).

Link GitLab Project to Mattermost Channel

Go to your GitLab project. Navigate to Project Settings > Integrations > Mattermost (or Mattermost Slash Commands). Enable the integration. Paste the webhook URL you just copied.

Optionally, set a webhook secret (a random string for security). Copy it into Mattermost's integration settings for consistency.

Choose which events trigger notifications: push events, merge request events, issue events, wiki page events, deployment notifications, and pipeline events. Select only the events your team cares about. Fewer events mean less noise.

Click "Save" and then "Test" to send a test notification. The test should appear in your Mattermost channel within seconds.

Using Slash Commands and Personal Notifications

Beyond channel notifications, the GitLab plugin includes slash commands for direct interaction.

First-Time Setup: Connect Your Account

Users must link their GitLab account to Mattermost before they can use most features. In Mattermost, type /gitlab connect. Mattermost will prompt the user to authorize Mattermost to access their GitLab account. The user approves, and their account is linked. The connection is per-user, not per-team.

Common Slash Commands

Once linked, users can type /gitlab todo to see their assigned GitLab to-do list (issues and MRs waiting for their action). They can type /gitlab subscriptions to list GitLab projects they're subscribed to (for notifications). They can type /gitlab help to see all available commands.

Personal Notifications

Users will also see a personal notification icon in the Mattermost sidebar. This shows mentions in MR comments, review requests, assigned issues, and open to-do items. Personal notifications are separate from channel notifications. A user can be notified in #dev-alerts about all pipeline failures, but only get a personal notification for pipelines on MRs they're reviewing.

Sidebar buttons also appear for users with active GitLab tasks. These provide a quick view of pending reviews and to-dos without switching to GitLab.

Troubleshooting Common Setup Issues

These are the mistakes most teams hit during setup.

OAuth Redirect URI Mismatch

You see an error like "redirect_uri does not match" or "The redirect URI does not match an existing one" when trying to authorize.

Cause: The redirect URI you registered in GitLab does not exactly match the one in Mattermost. Fix: Double-check that you used the secure protocol (not the insecure variant), that the domain matches your actual Mattermost URL exactly, and that the path is exactly /plugins/com.github.mattermost.plugin-gitlab/complete/oauth with no trailing slash at the end. If you're still stuck, delete the OAuth app in GitLab and re-create it with the correct URI.

Webhook Not Firing

You configured the webhook and clicked Test, but nothing appears in Mattermost.

Cause: The webhook URL is incorrect, or the webhook secret does not match. Fix: Verify the webhook URL is copied exactly (no extra spaces, no truncation). If you set a webhook secret in GitLab, paste the same secret into the Mattermost integration settings. Check your Mattermost error logs at System Console > Logs to see if any errors are reported. If the URL is correct but notifications still do not appear, the issue is likely a firewall blocking outbound traffic from GitLab to Mattermost. Contact your network administrator.

Plugin Does Not Appear in Marketplace

You log into Mattermost System Console but the Marketplace tab is missing or empty.

Cause: The Mattermost instance is not connected to the internet, or plugin access is disabled. Fix: Check System Console > Environment > Web Server > Enable Insecure Outbound Connections. If disabled, enable it temporarily (or whitelist Mattermost's plugin CDN in your firewall). Restart the Mattermost service with sudo systemctl restart mattermost. If you're running Mattermost in a restricted network, download the plugin manually from GitHub and upload it via System Console > Plugins > Plugin Management > Upload Plugin.

"Permission Denied" When Authorizing

A user connects their GitLab account but sees a permission error.

Cause: The OAuth scopes in the GitLab app are missing or incomplete. Fix: Go back to GitLab > Applications and edit the app. Ensure these scopes are checked: read_api, read_user, read_repository, write_repository. Save, then ask the user to disconnect and reconnect their account in Mattermost.

Frequently Asked Questions

How do I connect my GitLab account to Mattermost?

Users must authorize Mattermost to access their GitLab account. In Mattermost, type /gitlab connect and approve the OAuth request. After that, personal notifications (mentions, reviews, assigned issues) flow into Mattermost. The connection is per-user, not per-team.

What events trigger GitLab notifications in Mattermost?

Channel notifications are controlled per-project via the Mattermost webhook integration settings. You can choose: push events, merge request changes, issue creation or updates, wiki updates, deployment notifications, and pipeline status. Personal notifications (for mentions and reviews) appear regardless of channel settings once a user has connected their GitLab account.

Is the Omnibus Mattermost bundle still supported?

No. GitLab removed the bundled Mattermost in version 19.0 (January 2025). The bundle was deprecated in GitLab 18.9. If you're running GitLab 18.8 or earlier with bundled Mattermost, your Mattermost instance is no longer receiving security updates or feature releases. Upgrade to GitLab 19.0+ and migrate to the plugin-based integration.

Can I use the Omnibus bundle and the plugin at the same time?

No. The plugin is designed for standalone Mattermost instances. If you're running the deprecated Omnibus bundle, you must migrate to standalone Mattermost and the plugin integration. Mattermost provides a migration guide in their documentation.

What permissions do GitLab and Mattermost need to exchange?

The OAuth app in GitLab requires read_api, read_user, read_repository, and write_repository scopes. These allow Mattermost to fetch GitLab user info, read project data, and post notifications. Webhook integration requires no OAuth scopes; it uses a static webhook URL that GitLab pushes to.

Does the integration work with GitLab.com (SaaS)?

Yes. Register an OAuth app in your GitLab.com profile > Preferences > Applications. The setup is the same as self-hosted GitLab, but you use the GitLab.com domain as the GitLab URL. Personal and channel notifications work with GitLab.com projects just like self-hosted.

Can I route different GitLab projects to different Mattermost channels?

Yes. Each GitLab project has its own webhook settings. Set up a webhook for Project A pointing to #dev-alerts and a separate webhook for Project B pointing to #infra-alerts. Both will receive notifications independently.

What does the GitLab plugin cost?

The GitLab plugin for Mattermost is free and open-source. It is available on the Mattermost Marketplace at no cost. Your Mattermost server license (Community, Professional, or Enterprise) determines access to other features, but the GitLab plugin itself is not a paid add-on.

The Bottom Line

The GitLab + Mattermost integration brings real-time notifications and slash commands into your chat flow, eliminating context switching between tools. The plugin-based approach is now the only supported method; the deprecated Omnibus bundle was removed in GitLab 19.0. Setup takes about 30 minutes if you're familiar with OAuth and webhooks, or an hour if you're new to these concepts. The most common mistakes are OAuth redirect URI mismatches and webhook secret misconfigurations. If you want to skip the setup complexity entirely, managed Mattermost hosting comes with the GitLab integration pre-configured and ready to use.