mirror of
https://github.com/hanzoai/team.git
synced 2026-09-30 01:57:35 +00:00
b5f007d35e
* docs: resolve cross-file anchor mismatches from RST-to-MDX migration
The Sphinx-to-Docusaurus migration converted `:ref:`/`{ref}` links using
naive text-slugification, so anchors that pointed to headings in a
different file (e.g. release-summary tables linking into their
respective changelog pages) were emitted as same-page fragments and
silently resolved to nothing.
Built a label registry from the original Sphinx `.. _label:` / `(label)=`
targets to recover the true source file for each cross-reference, then
rewrote the affected links to point at the correct file + heading
anchor. Fixes 282 broken cross-file anchors, primarily in the mobile/
desktop/server release-summary pages, plus assorted same-page anchor
mismatches caught by re-auditing after the prior admonition/anchor fix.
* docs: manually resolve remaining anchor mismatches after cross-file audit
Hand-verified fixes for anchors that fuzzy-matching alone couldn't
safely resolve (confirmed against actual heading text/context, and in a
few cases against the original RST source, before applying):
- Typos and dropped words carried over from the original Sphinx docs
(e.g. "bot-acocunts", "auto-follow-all-new-channel-threads" ->
"follow-all-new-channel-threads").
- Sphinx auto-generated duplicate-heading IDs (#id1/#id3/#id4) resolved
to their real target headings.
- Numbered-step TOC links in enterprise-roll-out-checklist.mdx that
dropped the leading "N. " used in the actual heading slugs.
- Push-notification docs pointing at the wrong file entirely
(environment-configuration-settings instead of
push-notification-server-configuration-settings).
- SAML "saml-enterprise" label resolved to its true cross-file target
(authentication-configuration-settings#saml-2-0), recovered from the
original RST label definition that the automated registry missed
because it sat after an RST transition marker.
- sso-saml-technical references converted from broken same-page/
malformed-path anchors to correct page links.
* docs: fix SAML 2.0 anchor slug (saml-2-0 -> saml-20)
github-slugger strips periods rather than hyphenating them, so "SAML
2.0" slugifies to saml-20, not saml-2-0 as previously fixed.
* docs: fix broken path links found during docs/main migration cleanup
* docs: convert div.tab blocks to Docusaurus Tabs/TabItem components
* docs: restore missing Kubernetes deployment architecture diagrams
The RST-to-MDX migration never copied over the AWS/Azure/Oracle
architecture diagrams referenced by the deployment-architecture-at-scale
page, leaving broken images in each Tabs/TabItem.
* docs: fix 7 anchor mismatches from the fragment/heading audit
Covers three root causes from the anchor mismatch breakdown:
- Fragment repeated the target page's own title instead of a real
heading, so the link is simplified to point at the bare page.
- Heading exists verbatim but lives on a sibling settings page
(experimental-configuration-settings, push-notification-server-
configuration-settings) rather than environment-configuration-settings.
- A page path was mistakenly pasted into a same-page #fragment instead
of being used as a real cross-page link.
* docs: fix 8 anchor slugs that were close but didn't match the real heading
Repoints links whose fragment was a plausible guess (typo, reworded
heading, or wrong section) at the actual auto-generated slug of the
target heading, confirmed by inspecting each target page directly.
* docs: merge split Tabs blocks so tabs render horizontally
The div.tab conversion script split some sibling tab groups into
separate single-item Tabs blocks whenever a stray blockquote marker
sat between them, causing them to render stacked instead of as one
horizontal tab bar. Merges the MySQL/PostgreSQL and Team/Enterprise
Edition tab groups back into single Tabs blocks.
* docs: remove Azure tab and restore Kubernetes deploy content
The Mattermost Operator, Azure, and Oracle platform tabs on the
Kubernetes deployment guide were split across two separate Tabs
blocks (rendering stacked instead of as one tab bar) and all three
tab bodies were empty because the migration never flattened the
original RST include directives. Removes the unsupported Azure tab
and restores the Mattermost Operator and Oracle content from the
pre-migration RST sources as a single merged Tabs block.
* addresscoderabbitreview
* docs: unify Linux/Kubernetes/Containers deploy pages and fix FIPS/STIG placement
Kubernetes and Containers duplicated full install content across a top-level
page (Tabs) and orphaned sidebar subpages that nothing linked to. Reworked
both to follow the Linux page's pattern: shared content on the landing page,
platform-specific instructions live once in their own subpage.
Also removed configure-fips-at-install-time.mdx, which claimed FIPS is
available for native Linux installs — FIPS/STIG in Mattermost is a container
image property (Chainguard-based build), not available outside Docker/
Kubernetes. Consolidated all FIPS/STIG references onto
containers/fips-stig.mdx and pointed the Mattermost Operator subpage (not
Oracle OKE, which doesn't expose image selection) at it.
* docs: fix review findings — image alt text, Important callout markup, typo
- Replace generic alt="image" on scaling diagrams with descriptive text
identifying cloud provider and user scale.
- Convert raw div.important markup in deploy-containers.mdx to the
repo's <Important> component, matching usage elsewhere in the file.
- Fix "Matermost" typo in manage-your-display-options.mdx.
---------
Co-authored-by: Hanzo Dev <[email protected]>
214 lines
11 KiB
Plaintext
214 lines
11 KiB
Plaintext
---
|
|
title: "Connect GitLab to Mattermost"
|
|
---
|
|
import Tabs from '@theme/Tabs';
|
|
import TabItem from '@theme/TabItem';
|
|
|
|
<PlanAvailability slug="all-commercial" />
|
|
|
|
Minimize distractions and reduce context switching between your GitLab code repositories and your communication platform by integrating GitLab with Mattermost. You control which events trigger notifications beyond default events, including merges, issue comments, merge request comments, pipelines, pull reviews, and many more. Help your teams stay focused and productive with daily task summaries, real-time updates and notifications on new and closed merge requests, new and closed issues, and tag creation events, directly from Mattermost channel subscriptions.
|
|
|
|
Mattermost supports both Software-as-a-Service (SaaS) and on-premises versions of GitLab.
|
|
|
|
|
|
|
|
## Deploy
|
|
|
|
A Mattermost system admin must perform the following steps to deploy the GitLab integration.
|
|
|
|
### Install the integration
|
|
|
|
1. In Mattermost, from the Product menu <img src="/img/ui/products_E82F.svg" alt="Navigate between Channels, collaborative playbooks, and boards using the product menu icon." className="theme-icon" />, select **App Marketplace**.
|
|
2. Search for or scroll to GitLab, and select **Install**.
|
|
|
|
### Set up the integration
|
|
|
|
You can configure the GitLab integration using either the built-in setup wizard (recommended) or by following the manual configuration steps.
|
|
|
|
<Tabs>
|
|
<TabItem value="setup-wizard-recommended" label="Setup wizard (recommended)">
|
|
|
|
The recommended way to configure the GitLab integration is using the built-in setup wizard. The wizard guides you through each step of the configuration process, including creating the OAuth app in GitLab.
|
|
|
|
1. In any Mattermost channel, run the `/gitlab setup` slash command.
|
|
2. Follow the interactive prompts to complete the setup.
|
|
|
|
The wizard walks you through:
|
|
|
|
- Creating and configuring an OAuth app in GitLab
|
|
- Configuring the plugin settings in Mattermost
|
|
- Announcing the integration to your team
|
|
|
|
You can also run individual setup steps at any time using the following subcommands:
|
|
|
|
- `/gitlab setup oauth`: Configure the OAuth2 application in GitLab.
|
|
- `/gitlab setup announce`: Announce the integration availability to designated channels.
|
|
|
|
</TabItem>
|
|
<TabItem value="manual-configuration" label="Manual configuration">
|
|
|
|
If you prefer to configure the integration manually instead of using the setup wizard, follow the steps below.
|
|
|
|
**Register an OAuth app in GitLab**
|
|
|
|
1. Go to `https://gitlab.com/-/profile/applications` or `https://gitlab.YOURDOMAIN.com/-/profile/applications`, replacing `YOURDOMAIN.COM` with your GitLab URL, to register an OAuth app with GitLab.
|
|
2. Set the following values:
|
|
|
|
> - **Name**: `Mattermost GitLab Plugin - <YOUR COMPANY NAME>`
|
|
> - **Redirect URI**: `https://YOUR-MATTERMOST-URL.COM/plugins/com.github.manland.mattermost-plugin-gitlab/oauth/complete`, replacing `YOUR-MATTERMOST-URL.COM` with your Mattermost URL. This value must match the Mattermost server URL you use to log in.
|
|
|
|
3. Select `api` and `read_user` in **Scopes**.
|
|
4. Save your changes. Copy the **Application ID** and **Secret** fields in the resulting screen.
|
|
|
|
**Configure the integration in Mattermost**
|
|
|
|
1. In Mattermost, go to **System Console \> Plugins \> GitLab** and configure the following settings, then select **Save**:
|
|
|
|
> - Enter the **GitLab URL**, **GitLab OAuth Client ID**, and **GitLab OAuth Client Secret** you obtained when registering the OAuth app in GitLab.
|
|
>
|
|
> - Generate a **Webhook Secret** and **At Rest Encryption Key** by selecting **Generate**.
|
|
>
|
|
> - (Optional) **GitLab Group**: Lock the integration to a single GitLab group.
|
|
>
|
|
> - (Optional) **Enable Private Repositories**: Enable the ability to work with private repositories. Affected users are notified once private repositories are enabled, and must reconnect their GitLab accounts to gain access to private repositories.
|
|
>
|
|
> - (Optional) **Enable Child Pipeline Notifications**: When enabled, allows notifications for child pipeline events in addition to parent pipeline events. When disabled, only parent pipeline notifications are sent. This setting helps reduce notification noise in environments with complex CI/CD pipeline structures that use child pipelines extensively.
|
|
>
|
|
> - (Optional) **Enable Code Previews**: Control automatic expansion of GitLab file permalinks with code previews. Options include:
|
|
>
|
|
> - **Enable for public projects** (Default): Shows previews only for public GitLab repositories.
|
|
>
|
|
> - **Enable for public and private projects**: Shows previews for both public and private repositories.
|
|
>
|
|
> <div class="warning">
|
|
>
|
|
> <div class="title">
|
|
>
|
|
> Warning
|
|
>
|
|
> </div>
|
|
>
|
|
> This setting has the potential to leak confidential code into public channels in cases where users with access to private GitLab repositories post permalinks in public Mattermost channels. The plugin automatically generates previews using the poster's GitLab permissions, allowing other channel members without access to view the confidential code.
|
|
>
|
|
> </div>
|
|
>
|
|
> - **Disable**: Completely disables code preview functionality.
|
|
>
|
|
> **Supported Permalink Types:**
|
|
>
|
|
> - Single line permalinks: Shows target line plus 3 lines of context
|
|
> - File permalinks: Shows file information (no code preview)
|
|
> - Line range permalinks: Shows file information (no code preview)
|
|
>
|
|
> **Preview Limits:**
|
|
>
|
|
> - Maximum 10 lines displayed per preview (single line permalinks may show fewer preview lines due to context limits)
|
|
|
|
</TabItem>
|
|
</Tabs>
|
|
|
|
|
|
## Upgrade
|
|
|
|
We recommend updating this integration as new versions are released. Generally, updates are seamless and don't interrupt the user experience in Mattermost. Visit the [Releases page](https://github.com/mattermost/mattermost-plugin-gitlab/releases) for the latest release, available releases, and compatibility considerations.
|
|
|
|
## Enable
|
|
|
|
Once you setup the integration, notify your teams that they can [connect their GitLab accounts to Mattermost](#connect-a-gitlab-account-to-mattermost).
|
|
|
|
## Use
|
|
|
|
Users who want to use GitLab interconnectivity must connect their GitLab account to Mattermost.
|
|
|
|
Once connected, you'll receive direct messages from the GitLab bot in Mattermost when someone mentions you, requests a review, comments on, or modifies one of your merge requests/issues, or assigns you to an issue on GitLab.
|
|
|
|
### Connect a GitLab account to Mattermost
|
|
|
|
Run the `/gitlab connect` slash command in any Mattermost channel to link your Mattermost account with your GitLab account.
|
|
|
|
Disconnect a GitLab account by running the `/gitlab disconnect` slash command. Run the `/gitlab me` slash command to review which account is connected to GitLab.
|
|
|
|
Once connected, run the `/gitlab help` slash command to see what you can do.
|
|
|
|
### Get started
|
|
|
|
Run the `/gitlab todo` slash command to get a list of to-do's, assigned issues, assigned merge requests and merge requests awaiting your review. Alternatively, use the options located in the left sidebar.
|
|
|
|
Run the `/gitlab webhook` slash command to have GitLab send events to Mattermost. For example: `/gitlab webhook add group[/project]`
|
|
|
|
### Channel subscriptions
|
|
|
|
Run the `/gitlab subscriptions list` to review all of your subscriptions.
|
|
|
|
Run the `/gitlab subscriptions add group[/project] [features]` slash command to subscribe a Mattermost channel and receive posts for new merge requests, issues, or other features, from a GitLab project. To unsubscribe and stop receiving posts, run the `/gitlab subscriptions delete group[/project]` slash command.
|
|
|
|
The following features are supported for channel subscriptions:
|
|
|
|
- `merges` - Get notified when merge requests are merged
|
|
- `issues` - Get notified when issues are created
|
|
- `pushes` - Get notified when commits are pushed to a branch
|
|
- `issue_comments` - Get notified when comments are made on issues
|
|
- `merge_request_comments` - Get notified when comments are made on merge requests
|
|
- `tag` - Get notified when tags are created
|
|
- `pipeline` - Get notified about pipeline events (includes child pipeline events if enabled in plugin configuration)
|
|
- `wiki` - Get notified about wiki page events
|
|
- `releases` - Get notified when releases are created
|
|
- `deployments` - Get notified about deployment events
|
|
|
|
For example, to subscribe to release and deployment events: `/gitlab subscriptions add group[/project] releases,deployments`
|
|
|
|
For each project you want to receive notifications for or subscribe to, create a webhook in a channel where you want to watch events sent from GitLab by running the `/gitlab webhook` slash command. For example: `/gitlab webhook add group[/project]`
|
|
|
|
<Note>
|
|
|
|
For GitLab versions prior to 1.2:
|
|
|
|
1. In GitLab, go to the project you want to subscribe to, and select **Settings \> Integrations** in the sidebar.
|
|
2. Set the following values:
|
|
|
|
> - **URL**: `https://YOUR-MATTERMOST-URL.COM/plugins/com.github.manland.mattermost-plugin-gitlab/webhook`, replacing `https://YOUR-MATTERMOST-URL.COM` with your Mattermost URL. Ensure that you add `/plugins/com.github.manland.mattermost-plugin-gitlab/webhook` to the URL, or the webhook won't work.
|
|
> - **Secret Token**: Copy the webhook secret you generated earlier.
|
|
> - Select all the events in **Triggers**.
|
|
> - Add the webhook.
|
|
|
|
</Note>
|
|
|
|
### Create issues and manage comments
|
|
|
|
You can create GitLab issues and manage issue comments directly from Mattermost using slash commands and interactive modals.
|
|
|
|
#### Create a GitLab issue
|
|
|
|
Run the `/gitlab issue create` slash command to open an interactive modal where you can create a new GitLab issue. The modal allows you to perform the following actions:
|
|
|
|
- Set the issue title and description
|
|
- Assign labels
|
|
- Set the assignee
|
|
- Choose the milestone
|
|
- Select the target project
|
|
|
|
#### Attach comments to existing issues
|
|
|
|
Run the `/gitlab issue comment [issue-number]` slash command to attach a comment to an existing GitLab issue. This opens an interactive modal where you can compose and submit your comment directly from Mattermost.
|
|
|
|
### Update settings
|
|
|
|
Run the `/gitlab settings [setting] [value]` slash command to update your preferences for the integration:
|
|
|
|
- Turn personal notifications on or off.
|
|
- Turn reminders on or off when you connect initially each day.
|
|
|
|
## Get help
|
|
|
|
Mattermost customers can open a [Mattermost support case](https://support.mattermost.com/hc/en-us/requests/new). To report a bug, please open a GitHub issue against the [Mattermost GitLab plugin repository](https://github.com/mattermost/mattermost-plugin-gitlab).
|
|
|
|
For questions, feedback, and assistance, join our public [Integrations and Apps channel](https://community.mattermost.com/core/channels/integrations) on the [Mattermost Community Server](https://community.mattermost.com/) for assistance.
|
|
|
|
Mattermost Team Edition and Free customers can visit the Mattermost [peer-to-peer troubleshooting forum](https://forum.mattermost.com/c/trouble-shoot/16) to access the global Mattermost Community for assistance.
|
|
|
|
<Tip>
|
|
|
|
Watch [this on-demand webinar on release management with Mattermost and GitLab](https://mattermost.com/webinar/release-management-with-gitlab/) to learn how to streamline and standardize your release processes, while reducing the amount of effort required to ship your latest releases.
|
|
|
|
</Tip>
|