How to connect GitLab and Mattermost after GitLab 19 removed the bundled chat
If you run self-managed GitLab on GitLab 19 or later, the chat component is no longer bundled, so you connect the two products yourself. The link is built from GitLab's documented integration points and Mattermost's own single sign-on and server features, not from a single switch that appears in one settings page. Treat the connection as three separate pieces: notifications, slash commands and single sign-on. Each has its own owner, its own configuration and its own failure modes, so plan and test them one at a time.
Notifications send GitLab events, such as pushes, merge requests and pipeline results, into Mattermost channels. Slash commands let users act on GitLab from a Mattermost message. Single sign-on decides who can log in to each product and where identity comes from. Notifications usually fail quietly when a webhook URL changes or a channel is archived, slash commands fail when the request token or endpoint no longer matches, and single sign-on fails when the identity provider, redirect URL or user attributes drift. Confirm the GitLab-side method for each piece against the GitLab integration documentation for your installed version, because the exact steps, supported events and any required GitLab tier are not part of the facts supplied for this page. On the Mattermost side, confirm the single sign-on options your plan includes before you choose a method. The Mattermost pricing page lists SSO (SAML, OIDC, OAuth) from the Professional plan, and the Mattermost SAML single sign-on guide describes the SAML setup. Decide early whether GitLab users sign in to Mattermost through the same identity provider, and who owns the redirect URLs and client secrets. Record the owner of each integration, the account each bot or webhook uses, and the check that proves each piece still works after a GitLab upgrade or a Mattermost release. Mattermost ships server versions on the 16th of each month, so re-test after each change you adopt.
What you need before connecting GitLab to Mattermost
The integration depends on two independently upgraded systems, a shared identity setup and a network path that both sides can trust. Settle these five or six items before any configuration starts, so that the notification, slash command and SSO work does not stall on version or access questions.
A supported GitLab release
Confirm which GitLab release your self-managed instance runs and which one you plan to reach. GitLab requires upgrades to pass through required upgrade stops, which since GitLab 17.5 fall at x.2, x.5, x.8 and x.11. Check the current stop on the upgrade paths page before you start, because a skipped stop turns a simple integration project into an upgrade project.
A supported Mattermost server
Choose the Mattermost server release your organization will run and confirm it is still within its support window. Mattermost publishes a new server version on the 16th of each month, while Extended Support Releases carry longer support. Check the release table before you install, since a server that has reached end of life needs an upgrade before the integration work begins.
Administrator accounts on both sides
You need an administrator on the GitLab instance who can configure integrations and authentication, and an administrator on Mattermost who can create integrations, slash commands and SSO settings. Name both people in writing. Where one person holds both roles, record that dependency so that a single departure does not block renewals of credentials or certificates.
Network paths and certificates
Map which direction each request travels. GitLab must reach the Mattermost webhook endpoint, and Mattermost must reach GitLab for slash commands and SSO callbacks. Confirm that both hostnames resolve internally, that TLS certificates are issued by an authority both systems trust, and that egress rules allow the traffic. Air-gapped networks need the same paths mapped before deployment.
A Mattermost plan that includes SSO
Decide on the Mattermost plan before you design sign-in. According to the Mattermost pricing page, SSO through SAML, OIDC or OAuth is included from the Professional plan, while Mattermost does not list public prices and directs buyers to contact sales. Ask for a quote based on your seat count, and confirm that the plan covers the SSO method your identity provider supports.
A named owner for each integration
Assign one owner for notifications, one for slash commands and one for SSO, even if one team operates all three. Each owner should know which secrets, webhook URLs and certificates they manage, when they expire and who approves a change. Without named owners, a rotated token or changed webhook often breaks notifications silently.
Keeping Mattermost and GitLab on supported releases together
The two products run on different release calendars, so the integration needs its own upgrade plan. Mattermost publishes a new server version in binary form on the 16th of each month, and some releases are designated Extended Support Releases. The supplied release data lists v11.7 as an Extended Support Release, released on 2026-05-15 with support ending 2027-05-15, while the previous ESR, v10.11, reached end of life on 2026-08-15. GitLab ships a minor release on the third Thursday of each month, patches twice a month, and requires upgrades to pass through required upgrade stops. Confirm the current support window for every Mattermost version you run on the Mattermost server releases page before you fix an upgrade date, because a version that is in support today may not be in support when your change window arrives.
A release on either side can break a link that worked yesterday. A Mattermost version that reaches end of support stops receiving fixes, which leaves the notification and slash command path exposed. A GitLab upgrade can change how notifications, webhooks or the integration settings behave, and a GitLab upgrade that moves through a required stop may need a longer window than a routine patch. Treat each upgrade on either side as a change to the integration. Before the upgrade, record the working state: the webhook or integration endpoint, the channel that receives messages, the slash command configuration and the SSO login path. After the upgrade, post a test message, run a slash command, and sign in through the SSO path from a test account. Run this check on both sides, because a successful GitLab upgrade does not prove that Mattermost still accepts the request, and the reverse is also true.
Plan the sequence and the owner before the first upgrade. Decide whether Mattermost or GitLab moves first, and keep the older side on a version that both still support during the window. Assign one person to own the integration test script and one to own the rollback decision. Ask your Mattermost contact or your DeployOpen team to confirm which Mattermost release lines are current at the time you plan, and keep a written record of the versions in use on each side so that the next upgrade starts from known facts.
Configuration sequence for the GitLab and Mattermost link
This sequence connects a self-managed GitLab instance to a separately run Mattermost server in a test environment first, then adds notifications, slash commands and single sign-on in order. Each step closes with a check, so the team knows what works before any change reaches production.
Confirm the integration method and endpoint
The GitLab administrator and the Mattermost administrator agree in writing on the integration method, the Mattermost base URL and the channels that will receive events, all in a test environment. Confirm in the GitLab and Mattermost documentation which method your versions support, and confirm that the Mattermost server runs on a separate, supported release, since GitLab 19 no longer bundles it. Check that GitLab can reach the Mattermost endpoint over the network path you plan to use, including any proxy or firewall rules. The step is done when both administrators have signed off on the method and a basic request from the GitLab host reaches Mattermost successfully.
Prepare the Mattermost team and accounts
A Mattermost administrator creates or selects the team, creates the channels for notifications and sets the posting permissions. Then create the account the integration will use, either a bot account or the incoming webhook that the chosen method requires, and give it access only to the channels it needs. Enable the Mattermost setting for that method in the System Console and record the resulting webhook or token in your secrets store, not in a shared document. The check is a manual test: post a message from the integration account into the named test channel and confirm it appears with the expected sender name.
Configure GitLab notifications to Mattermost
A GitLab administrator sets up the Mattermost notification integration at the level agreed in step one, instance, group or project, so inheritance is predictable. Select only the events the teams need, such as merge requests, pushes or pipeline results, and map each event to a named channel. Keep the first configuration narrow so that noisy events do not flood channels during testing. The check is a test notification from GitLab that lands in the named test channel, with the project and event shown correctly in the message. If the message does not arrive, check the webhook value, the channel name and the network path before changing anything else.
Enable and test slash commands
Enable the slash command feature in Mattermost, then create the command entry that points back to GitLab, using the URL and token that the chosen integration method provides. Set the command trigger word to a name agreed with the teams, and limit where it runs to the test channel first. Confirm that the Mattermost setting for custom or integration commands is permitted on this server, since some plans and policies restrict it. The check is a slash command typed in the test channel that returns a response from GitLab, and a second check that a user without GitLab access receives the expected refusal rather than project data.
Configure single sign-on with SAML
Configure SAML single sign-on in Mattermost using the identity provider your organization already runs, following the Mattermost SAML guide and checking that your license tier includes SSO. Confirm the attribute mapping for email and username so that a returning user matches an existing account rather than creating a duplicate. Keep GitLab sign-in and Mattermost sign-in as separate configurations, and do not assume one setting covers the other. The check is a test login with a pilot account, which should either create a new account or match the expected existing one, with the email and username correct. Repeat the test with a second account to confirm that the mapping behaves the same way.
Document and rehearse the rollback plan
Write a rollback plan that lists each change made in steps two to five, the order to reverse them and the owner of each reversal. Export and store a copy of the Mattermost configuration and note the GitLab integration settings before any production change, so the previous state can be restored. Disable the GitLab notification integration, remove the slash command, deactivate the integration account and turn off SAML, in that order, then confirm each one in the test environment. The check is that after the rollback, GitLab sends no new notifications, the command returns nothing, and a test login uses the previous method. Keep this plan with the change record before production work starts.
How GitLab events, users and channels map to Mattermost
This table pairs each GitLab object or event with its Mattermost target, the team that should own it, and the decision it needs before rollout. Read it as a checklist: every row is a choice someone must make and record, and the rows about identity and deprovisioning carry the most risk. SCIM and LDAP group sync run on the identity provider side, so confirm those behaviors against the current Mattermost and GitLab documentation before relying on them.
| GitLab object or event | Mattermost target | Owner | Decision it needs |
|---|---|---|---|
| Project events (push, tag, new issue) | One channel per project or a shared channel per team | Project maintainer with platform team sign-off | Which events are worth interrupting people, and whether noisy projects share a channel |
| Group events and epics | A group-level or announcements channel | Group owner | Whether group-wide activity goes to one channel or stays with each project |
| Merge request opened, reviewed or merged | Review or team channel, optionally direct messages to reviewers | Engineering manager | Whether reviewer pings go to a channel or to individuals, to limit noise |
| Pipeline status (failed or fixed) | Dedicated build channel, filtered to broken pipelines | CI/CD owner | Whether to alert only on default-branch failures to prevent alert fatigue |
| Slash commands run as a user | Channel where the command is typed, responses returned to the user | Platform team | Which user identity runs commands, and which commands non-admins may use |
| GitLab username or email to Mattermost account | Mattermost user matched through SSO attributes | Identity team | Which attribute is the unique key, and how to handle duplicate or changed emails |
| Group membership to channel membership | Channels joined through sync or manual invitation | Identity team with channel owners | Whether channel access follows identity provider groups or is managed in Mattermost |
| User deprovisioning | Account deactivated and sessions revoked in Mattermost, GitLab access removed | Identity team and HR offboarding owner | Confirm in both products that removing a user at the identity provider disables access in each, and test it |
| SCIM and LDAP group sync | Identity provider configuration feeding both products | Identity team | Confirm supported behavior against the Mattermost and GitLab documentation before design is final |
Notifications, slash commands and SSO need different setup paths
Notifications flow one way: GitLab posts events such as pipeline results, merge request activity or deployment status into a Mattermost channel. The Mattermost side issues an incoming webhook URL tied to one channel, and that URL is the secret. Anyone who holds it can post into the channel, so it belongs in the GitLab integration settings, not in project code or a shared document.
- Mattermost configuration: Create an incoming webhook for a single channel, and confirm that a system administrator has enabled webhook integrations on the server.
- Secret holder: The webhook URL is stored in GitLab's integration settings. To rotate it, generate a new webhook in Mattermost and update GitLab in the same change window.
- Scope: Decide whether the integration is set per project, per group or at instance level, and choose only the events the channel needs. Pipeline alerts are the usual source of noise.
- What breaks first: Messages stop silently when the webhook is deleted, the target channel is archived, or the Mattermost URL changes after a domain move.
- Confirm: Check the GitLab-side method and the available event list in the GitLab integration documentation for your installed version before you build.
Before go-live, send a test event from a non-production project to the intended channel, then point a deliberately invalid URL at a test project and confirm that the team sees the failure.
Slash commands run in the other direction. A user types a command in Mattermost, Mattermost sends a request to an endpoint you control, and that endpoint replies in the channel. The shared token Mattermost sends is what lets the endpoint confirm the request is genuine. Because the endpoint calls GitLab on the user's behalf, its credentials carry more risk than a webhook.
- Endpoint: Decide which service receives the command, where it runs and how it reaches your GitLab instance. Confirm the GitLab-side method and supported commands in the GitLab integration documentation for your installed version.
- Secret holder: Mattermost holds the command token and the endpoint URL. The service that calls GitLab holds a separate GitLab credential, which should be limited to the actions the command needs.
- Least privilege: Start with read-only commands. Limit write actions to named channels and named roles, and confirm who can run each command through channel membership.
- What breaks first: Users see a failure message when Mattermost cannot reach the endpoint, when the token is rotated on one side only, or when the endpoint presents a certificate that the Mattermost server does not trust.
- Data exposure: Confirm whether a command can return content from private GitLab projects to channel members who lack access to those projects.
Test each command with one user who holds the right GitLab role and one who does not. The second user should be refused, and no sensitive detail should appear in the channel.
Single sign-on is configured on the Mattermost server. Mattermost supports SAML, OIDC and OAuth, and the pricing page lists SSO and AD/LDAP user sync from the Professional plan. This tab covers Mattermost only, because GitLab's own sign-in is configured separately. Pick one protocol per deployment based on what your identity provider and operations team can maintain.
- Protocol choice: Select SAML, OIDC or OAuth, and confirm the plan that includes your choice. For SAML details, see the Mattermost SAML single sign-on guide.
- Secret holder: For SAML, Mattermost trusts the identity provider's signing certificate. For OIDC or OAuth, the client secret sits in Mattermost configuration and must be rotated before it expires.
- Callback and identifier values: The redirect or assertion consumer URL and the entity ID must match exactly between the identity provider and Mattermost, including scheme and trailing slashes.
- What breaks first: Users get a login error when a URL or entity ID differs, when a certificate or client secret expires, or when clocks on the two systems drift far enough to invalidate assertions.
- Lifecycle: Confirm how a user removed in the identity provider loses access to Mattermost, and whether group membership maps to team or channel roles.
Test three cases: a new user, an existing user and a user disabled in the identity provider. Keep a documented local administrator account for recovery before you change SSO settings on a live server.
Securing the link between GitLab and Mattermost
The GitLab to Mattermost link carries pipeline results, merge request activity and slash command actions into a chat system that many people can read. Each control below narrows what the link can expose or change, and each has an owner on both sides.
Store webhook URLs and tokens in a secrets store
Incoming webhook URLs in Mattermost act as credentials, and anyone holding one can post into its channel. Keep them in a secrets manager you already operate, not in project variables that every maintainer can read. Rotate the URL when a person who configured it leaves or changes role, and confirm the old URL stops posting. Ask your team which systems hold a copy of each URL, because a rotation that misses one copy leaves the old credential working in practice.
Restrict channels that receive security events
Pipeline failures, merge request activity and security findings are useful to developers but can reveal unpatched issues to a wide audience. Route security-related notifications to a private or limited channel with named members, and keep general build status in a broader channel. Review channel membership on a schedule, since a public channel that receives vulnerability notices is a disclosure risk. Confirm which GitLab events each webhook sends before enabling it.
Limit slash command actions by role
Slash commands that trigger GitLab actions can act on behalf of a linked account, so they need the same permission model as the GitLab UI. Restrict which Mattermost roles can run commands that change state, and check that the GitLab user linked to each Mattermost account has only the project access that person needs. Document which commands are read-only and which can modify issues or pipelines, and review that list when either product adds commands.
Enforce SSO and disable password login
If policy requires central authentication, both servers should sign users in through the same identity provider, and each should refuse password logins for accounts that the policy covers. Mattermost supports SAML, OIDC and OAuth single sign-on from the Professional plan, and GitLab supports SAML and OmniAuth providers. Confirm that account deprovisioning in the identity provider removes access on both systems, since a disabled user in one product who still has an active account in the other is a common gap.
Keep both servers on supported releases
Each server must receive security fixes for the link to remain trustworthy. GitLab backports security fixes to the previous two monthly releases, while bug fixes reach only the current stable release. Mattermost releases server binaries on the 16th of each month, and its Extended Support Release line has its own end dates. Track both support calendars, and schedule integration tests after each upgrade of either side, because webhook and slash command behavior can change between versions.
Log integration changes in both audit trails
Creating a webhook, changing its channel, or enabling a slash command should leave a record in the system that changed. Confirm which of these changes each product records in its audit log and how long those logs are kept, then forward them to your central log store. Include the GitLab hardening guidance in your review of the GitLab side, since it covers application settings and configuration files, but confirm each setting against your own version rather than assuming a default.
Common failures when GitLab and Mattermost stop talking
This table maps common symptoms of a broken GitLab and Mattermost link to their likely causes and the first checks to run. Start with the symptom that matches what users see, then confirm each fix against the current GitLab and Mattermost documentation for your versions. Most failures trace back to changed endpoints, certificates, identity settings or token ownership.
| Symptom | Likely cause | Fix |
|---|---|---|
| Notifications stop after a GitLab upgrade | Integration settings were reset or not carried over, or the Mattermost webhook URL changed. | Check the integration on the project, group or instance, re-enter the webhook URL, and send a test event. Confirm the steps in the GitLab release notes for your target version. |
| Channels flooded or duplicate messages | The same event is sent through a project webhook and a group or instance integration, or pipeline alerts fire on every job. | List every integration pointing at the channel and remove duplicates. Limit pipeline notifications to failed or broken pipelines, and confirm the event settings in GitLab documentation. |
| Slash commands time out | Mattermost cannot reach the GitLab endpoint, or GitLab cannot reach the Mattermost host through a proxy, firewall or outbound request restriction. | Test connectivity in both directions from the relevant hosts. Check proxy timeouts, egress allowlists and GitLab outbound request settings, then confirm the endpoint requirements in the Mattermost and GitLab docs. |
| Certificate trust errors between servers | The server uses a private or internal certificate authority that the other server does not trust, or the chain is incomplete or expired. | Verify the full certificate chain and subject names, then add the internal CA to the trust store used by the calling service. Restart affected services and confirm the procedure in GitLab custom certificate guidance. |
| SSO users land in the wrong team or cannot log in | The identity provider changed its issuer, entity ID, redirect URI or attribute and group mapping, so Mattermost no longer matches claims to teams. | Compare the current identity provider settings with the Mattermost SSO configuration, then test with a new user. Review team mapping and user sync rules, and confirm requirements in the Mattermost SAML single sign-on documentation. |
| Tokens expire or stop working after a staff change | The integration token belongs to a personal account that was deactivated, removed or had its access reduced. | Identify every token and bot tied to the departing user. Move integrations to a dedicated service account, issue new credentials, and record an owner for each. Confirm token lifetime and revocation behavior in both products' documentation. |
| Integration breaks after a Mattermost upgrade | The Mattermost server version is out of support or changed an API or integration behavior that GitLab relies on. | Check the running Mattermost version against the server releases page and plan an upgrade to a supported release. Test notifications and slash commands in a staging channel before changing production. |
| Integration worked before but no longer exists after GitLab 19 | The deployment assumed the bundled Mattermost component, which was removed in GitLab 19, so the configuration points at a service that no longer runs. | Confirm that a standalone Mattermost server is installed and reachable, then reconfigure the GitLab integration to that server. Review the GitLab 19 upgrade notes to confirm what was removed and what replaces it. |
Questions buyers ask before connecting GitLab to Mattermost
Can our own team connect GitLab to Mattermost?
Yes, if you already run both platforms and have people who can change their administration settings. The work has two sides: GitLab needs its Mattermost integration configured for notifications and slash commands, and Mattermost needs its server, channels and any single sign-on prepared to receive them. Teams that have not configured a chat integration before usually find the GitLab side simple and the Mattermost side slower, mainly because of channel design and permissions. Single sign-on adds an identity provider dependency, so a team without that expertise should plan for a partner or a dedicated engineer for the identity part. Ask a partner to show which parts of the work they would hand to your staff and which they would carry out themselves.
What drives the cost of a GitLab and Mattermost integration?
The main drivers are the number of GitLab projects and Mattermost channels that receive notifications, the number of identity sources, the scope of single sign-on, and whether Mattermost high availability is already in place or must be built. Each additional project-to-channel mapping adds design and testing, and each identity source adds mapping and validation. On the software side, Mattermost sells Professional, Enterprise and Enterprise Advanced plans as prepaid annual subscriptions based on seat licenses, and its pricing page lists no public prices and directs buyers to contact sales. GitLab's own subscription is a separate cost. Ask a partner for a quote that separates one-time configuration work from any recurring support, and that states which licenses your plan requires.
How long does connecting GitLab to Mattermost take?
The duration depends on the scope you agree and on how long approvals take in your organization. A basic notification setup for a small number of projects moves faster than single sign-on across several identity sources, which needs testing for each login path, group mapping and account fallback. Change approvals, security reviews and the availability of a change window can add more time than the technical work. Because no researched duration applies to this integration, ask a partner to tie the timeline to a written scope with named milestones, a test environment phase, and the approvals your organization must obtain before production changes.
What does the integration need from our team?
Five roles or resources shape the work. An identity provider owner must supply the single sign-on configuration and group claims. A GitLab administrator must approve the integration settings and any project or group defaults. A Mattermost administrator must configure the server, channels and permissions. You also need a test environment that mirrors production closely enough to validate notifications and sign-in, and a change window for the production switch. Name these people before the work starts, because delays in identity configuration or change approval are the most common reasons a schedule slips. A partner's written scope should list which of these tasks it performs and which it expects your staff to complete.
Does the integration survive a GitLab major release?
The integration has to be verified after each GitLab upgrade, and a major release is the point where that check matters most. GitLab ships a major release yearly, and upgrades must pass through required upgrade stops, which fall at versions x.2, x.5, x.8 and x.11, such as 19.2, 19.5, 19.8 and 19.11. Each stop is a chance to confirm that the integration settings, notification templates and slash command configuration still work with the target version. Check the release notes for the version you plan to reach, test the integration on a staging instance first, and keep a rollback plan. Ask a partner how they handle upgrade testing for both GitLab and Mattermost, and whether that testing is part of the scope or a separate retainer.
Which Mattermost plan do we need for SSO and high availability?
The plan decides which single sign-on and high availability features you can use. According to Mattermost's pricing page, SSO through SAML, OIDC and OAuth, along with AD/LDAP user sync, is included from the Professional plan. High availability clustering and FIPS 140-3 compliance start at Enterprise, and air-gapped deployment is listed for Enterprise Advanced. High availability also depends on shared file storage on Amazon S3, an S3-compatible service or NAS mounted on every node, because local file system storage will not work correctly and risks corrupting files. Confirm current plan contents and pricing with Mattermost sales, and ask a partner to price the storage and database changes that high availability would require.
How do Mattermost release timing and support windows affect the integration?
Mattermost publishes server releases in binary form on the 16th of each month, and it also issues Extended Support Releases. According to Mattermost's server releases page, v11.7 is an Extended Support Release released on 2026-05-15 with support ending 2027-05-15, and the previous ESR, v10.11, reached end of life on 2026-08-15. If you track monthly releases, you will need to retest the GitLab integration more often. If you choose an ESR, you get a longer support window but may run the GitLab integration against a server version that newer GitLab releases no longer test against. Decide your Mattermost release track before the integration is built, and record the chosen track in your change management process so upgrades follow a known schedule.
How DeployOpen scopes and delivers the GitLab and Mattermost link
DeployOpen plans, implements, integrates, hardens, documents and supports self-hosted open-source platforms inside your own infrastructure, including the GitLab and Mattermost link. Engagements are fixed-scope, with the scope, deliverables and timeline agreed in writing before work starts.
How we scope
- Confirm your GitLab edition, version and install method before choosing an integration path
- Record which notification events, slash commands and sign-in flows the written scope covers
- Confirm your Mattermost plan, since SSO and high availability depend on the tier you hold
- Agree in writing which teams, projects and channels receive each notification type
How we build
- Configure GitLab notifications and slash commands against your agreed Mattermost channels
- Set up single sign-on between the two systems using your chosen identity provider
- Test notifications, command responses and sign-in in a non-production environment first
- Check how the link behaves during GitLab upgrade stops and Mattermost monthly releases
How we hand over
- Document every integration setting, service account and channel mapping in the handover pack
- Record the steps to rotate tokens and secrets used by the integration
- Walk your operations team through the runbook for failed notifications and sign-in issues
- Provide a test script your team can rerun after each GitLab or Mattermost upgrade
How we support
- Offer ongoing support and upgrade work for the integration as a retainer
- Review the integration when GitLab or Mattermost release versions move to a new support window
- Re-test notifications and sign-in after changes to identity providers or network rules
- Confirm support scope and response expectations in writing before the retainer starts
