Mattermost GitLab Plugin

repository·master·Indexed 41 days ago

https://github.com/mattermost/mattermost-plugin-gitlab

A two-way integration plugin for Mattermost that connects GitLab (SaaS or on-premises) to Mattermost channels and users. It enables automated notifications for issues, merge requests, and pipelines, provides personal notifications via a GitLab bot, and displays real-time counts for reviews and assignments in the Mattermost sidebar.

Tokens
15.7K
Snippets
62
Records
75
Agent score
100%

What's inside Mattermost GitLab Plugin

  1. Overview of Mattermost GitLab Plugin features

    master

    The Mattermost GitLab Plugin provides a two-way integration between Mattermost and GitLab (supporting both SaaS and on-premises versions). Key features include:

    • Channel Subscriptions: Send notifications from GitLab groups or repositories to Mattermost channels based on specific events.
    • Personal Notifications (GitLab bot): Connect individual GitLab accounts to Mattermost users to receive direct messages for mentions, review requests, comments, or assignments.
    • Sidebar Buttons: Display real-time counts for reviews, todos, assigned issues, and assigned merge requests directly in the Mattermost sidebar.
  2. Configure GitLab event notifications for Mattermost channels

    master

    You can subscribe Mattermost channels to GitLab events. When configuring webhooks in GitLab, you can specify which events trigger a notification in Mattermost.

    Supported event types:

    • issues: New and closed issues.
    • merges: New and closed merge requests.
    • pushes: Code pushes.
    • issue_comments: New issue comments.
    • merge_request_comments: New merge-request comments.
    • pipeline: Pipeline status updates.
    • tag: Tag creation.
    • pull_reviews: Merge request reviews.
    • merge_request_assigns: Assignment and unassignment notifications.
    • label:"<labelname>": Filter by label (Note: must also include merges or issues in the feature list).

    Default configuration: If no specific events are chosen, the plugin defaults to merges,issues,tag.

  3. Release new versions of the plugin via Makefile

    master

    The plugin uses a Makefile to automate the release process. The version is automatically determined at compile time based on Git tags and the short commit hash, unless the version field in plugin.json is manually maintained.

    Use the following commands to trigger different release types:

    # Patch Releases
    make patch
    make patch-rc
    
    # Minor Releases
    make minor
    make minor-rc
    
    # Major Releases
    make major
    make major-rc
  4. Use GitLab Popouts for state synchronization

    master

    The plugin supports Mattermost popouts (secondary windows). It uses a messaging protocol to synchronize the state of the Right Hand Sidebar (RHS) between the main window and the popout window.

    Popout Communication Protocol:

    • Main Window to Popout: The main window can send GET_POPOUT_STATE to the popout. The popout responds with SEND_POPOUT_STATE containing the rhsViewType, rhsState, and channelId.
    • Popout to Main Window: When a popout is initialized, it sends GET_POPOUT_STATE to the parent. The parent responds with the current state to ensure the popout reflects the correct context.

    This ensures that if a user changes a view or channel in the main window, the popout stays in sync.

  5. Use the GitLab connect slash command

    master

    The GitLab plugin supports a special slash command /gitlab connect which is designed to facilitate connection via the browser.

    When this command is used within a Mattermost Desktop application, the plugin intercepts the message and triggers an ephemeral post containing instructions or a link to connect using the browser. This command is specifically handled by the slashCommandWillBePostedHook to ensure a smooth transition for desktop users.

    /gitlab connect
  6. Understand the GitLab plugin Redux state structure

    master

    The GitLab plugin manages its internal state using a Redux store composed of several specialized reducers. When interacting with the plugin's webapp, the state is organized into the following logical domains:

    Connection & Configuration

    • connected: Boolean indicating if the GitLab connection is active.
    • gitlabURL: The URL of the connected GitLab instance.
    • organization: The GitLab organization name.
    • username: The GitLab username.
    • clientId: The GitLab client ID.
    • settings: An object containing plugin settings:
      • sidebar_buttons: String defining which buttons to show (defaults to Constants.SETTING_BUTTONS_TEAM).
      • daily_reminder: Boolean.
      • notifications: Boolean.

    GitLab Data

    • gitlabUsers: A record mapping Mattermost user IDs to GitlabUsersData.
    • yourProjects: An array of Project objects.
    • lhsData: Data used for the Left Hand Side (LHS) view.
    • reviewDetails: An array of Item objects representing review details.
    • yourPrDetails: An array of Item objects representing the user's own Pull Request details.

    UI & Modal State

    • rhsViewType: Tracks the current view in the Right Hand Side (RHS) component (e.g., SUBSCRIPTIONS or sidebar_right).
    • rhsState: A string representing the current RHS state.
    • rhsPluginAction: Data for specific RHS plugin actions.
    • isCreateIssueModalVisible: Boolean visibility state for the Create Issue modal.
    • createIssueModal: Data for the Create Issue modal, including postId, title, and channelId.
    • isAttachCommentToIssueModalVisible: Boolean visibility state for the Attach Comment modal.
    • postIdForAttachCommentToIssueModal: The postId associated with the Attach Comment modal.
    • subscriptions: A record mapping channel IDs to SubscriptionData.
    • popoutChannelId: The channel ID of the parent window when using popout windows.
  7. Register GitLab Right Hand Sidebar (RHS) component

    master

    The plugin registers a unified Right Hand Sidebar (RHS) component named GitLabRHS. This component handles multiple views, including channel subscriptions.

    When registering the component via the PluginRegistry, the plugin receives showRHSPlugin and toggleRHSPlugin functions. These are used to programmatically open or toggle the GitLab sidebar from other parts of the Mattermost UI (like the App Bar or sidebar buttons).

    const {showRHSPlugin, toggleRHSPlugin} = registry.registerRightHandSidebarComponent(GitLabRHS, 'GitLab');
    
    // Example: Dispatching the action to show the RHS
    store.dispatch(setShowRHSAction(() => store.dispatch(showRHSPlugin)));
  8. Handle GitLab WebSocket connection events

    master

    The plugin provides higher-order functions to create WebSocket event handlers that interact with the Redux store. These handlers manage the connection state, settings, and sidebar button visibility when the WebSocket connects, disconnects, or reconnects.

    • handleConnect(store): Returns a handler that dispatches ActionTypes.RECEIVED_CONNECTED with connection data and default settings (including sidebar_buttons: Constants.SETTING_BUTTONS_TEAM and daily_reminder: true).
    • handleDisconnect(store): Returns a handler that dispatches ActionTypes.RECEIVED_CONNECTED with connected: false and resets credentials.
    • handleReconnect(store, reminder = false): Returns an async handler that attempts to re-establish connection using getConnected and refreshes Left Hand Side (LHS) data if successful.
    • handleRefresh(store): Returns a handler that refreshes LHS data if the plugin is currently connected.
    import { handleConnect, handleDisconnect, handleReconnect, handleRefresh } from './websocket';
    
    // Example usage within a WebSocket listener:
    const socket = new WebSocket(url);
    
    // Initialize handlers with the Redux store
    const onConnect = handleConnect(store);
    const onDisconnect = handleDisconnect(store);
    
    socket.onmessage = (event) => {
        // The handlers are designed to be called with the message object
        onConnect(event);
    };
    
    socket.onclose = () => {
        onDisconnect();
    };
  9. Use GitLab related icon components

    master

    The webapp/src/utils/icons.tsx module exports several React components used to render GitLab-specific icons within the Mattermost web application. Each icon component accepts an IconProps object to control its appearance.

    IconProps

    All icon components follow the same prop interface:

    • fill (string): The color of the icon (required).
    • width (number, optional): The width of the SVG. Defaults to 13 for most icons, or 16 for status-specific icons.
    • height (number, optional): The height of the SVG. Defaults to 13 for most icons, or 16 for status-specific icons.

    Available Icon Components

    ComponentDescription
    GitLabIssuesIconRepresents GitLab issues
    GitLabMergeRequestIconRepresents GitLab merge requests
    GitLabReviewsIconRepresents GitLab reviews
    GitLabTodosIconRepresents GitLab todo items
    GitLabMergeRequestClosedIconRepresents a closed merge request (default size: 16x16)
    GitLabMergedIconRepresents a merged merge request (default size: 16x16)
    GitLabIssueClosedIconRepresents a closed issue (default size: 16x16)
    GitLabIssueOpenIconRepresents an open issue (default size: 16x16)
    import { GitLabIssuesIcon, GitLabMergeRequestIcon } from 'webapp/src/utils/icons';
    
    // Example usage:
    const MyComponent = () => (
        <div>
            <GitLabIssuesIcon fill="#666" width={20} height={20} />
            <GitLabMergeRequestIcon fill="red" />
        </div>
    );