-
Notifications
You must be signed in to change notification settings - Fork 87
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Update GitLab plug-in documentation (#143)
Co-authored-by: Romain Maneschi <[email protected]> Co-authored-by: Justine Geffen <[email protected]> Co-authored-by: Rohit Jain <[email protected]> Co-authored-by: Ben Schumacher <[email protected]>
- Loading branch information
5 people
authored
Sep 28, 2020
1 parent
e43ead5
commit a5e7c6a
Showing
12 changed files
with
242 additions
and
39 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1 @@ | ||
| root: ./docs/ |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # Mattermost/GitLab Integration | ||
|
|
||
| [](https://circleci.com/gh/mattermost/mattermost-plugin-gitlab) [](https://codecov.io/gh/mattermost/mattermost-plugin-gitlab) | ||
|
|
||
| This plugin supports a two-way integration between Mattermost and GitLab. For a stable production release, please download the latest version [in the Releases tab](https://github.com/mattermost/mattermost-plugin-gitlab/releases) and follow [these instructions](./#2-configuration) for install and configuration. Check the Plugin Marketplace. | ||
|
|
||
| This plugin supports Software-as-a-Service (SaaS) or on-premises versions of GitLab. | ||
|
|
||
| Originally developed by [Romain Maneschi](https://github.com/manland) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,16 @@ | ||
| # Table of Contents | ||
|
|
||
| * [Mattermost/GitLab Integration](README.md) | ||
| * [Feature Summary](feature-summary.md) | ||
|
|
||
| ## Setup | ||
|
|
||
| * [Installation](setup/installation.md) | ||
| * [Configuration](setup/configuration.md) | ||
| * [Updating the Plugin](setup/updating-the-plugin.md) | ||
|
|
||
| ## Development | ||
|
|
||
| * [Environment](development/environment.md) | ||
| * [Help Wanted!](development/help-wanted.md) | ||
| * [Help and Support](help-and-support.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,21 @@ | ||
| # Environment | ||
|
|
||
| ## Development | ||
|
|
||
| This plugin contains both a server and web app component. | ||
|
|
||
| Use `make dist` to build distributions of the plugin that you can upload to a Mattermost server. | ||
|
|
||
| Use `make check-style` to check the style. | ||
|
|
||
| Use `make deploy` to deploy the plugin to your local server. Before running `make deploy` you need to set a few environment variables: | ||
|
|
||
| ``` | ||
| export MM_SERVICESETTINGS_SITEURL=http://localhost:8065 | ||
| export MM_ADMIN_USERNAME=admin | ||
| export MM_ADMIN_PASSWORD=password | ||
| ``` | ||
|
|
||
| ## | ||
|
|
||
| For additional information on developing plugins, refer to [our plugin developer documentation](https://developers.mattermost.com/extend/plugins/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| # Help Wanted! | ||
|
|
||
| This project, [mattermost-plugin-gitlab](https://github.com/mattermost/mattermost-plugin-gitlab), is a fork of [mattermost-plugin-github](https://github.com/mattermost/mattermost-plugin-github). Thanks to all contributors of it. | ||
|
|
||
| If you're interested in joining our community of developers who contribute to Mattermost - check out the current set of issues [that are being requested](https://github.com/mattermost/mattermost-plugin-gitlab/issues?q=is%3Aissue+is%3Aopen+label%3AEnhancement). | ||
|
|
||
| You can also find issues labeled ["Help Wanted"](https://github.com/mattermost/mattermost-plugin-gitlab/issues?q=is%3Aissue+is%3Aopen+label%3A%22Help+Wanted%22) in the GitLab plugin repository that we have laid out the primary requirements for and could use some coding help from the community. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,77 @@ | ||
| # Feature Summary | ||
|
|
||
| ## GitLab to Mattermost Notifications | ||
|
|
||
| ### Channel Subscriptions | ||
|
|
||
| Notify your team of the latest updates by sending notifications from your GitLab group or repository to Mattermost channels. When team members log in the first time to Mattermost each day, they can get a post letting them know what issues and merge requests need their attention. They can also get a refresh of new events by clicking on *Refresh* and from every webhook configured in GitLab. | ||
|
|
||
| You can specify which events trigger a notification. They can see: | ||
|
|
||
| - issues - includes new and closed issues | ||
| - merges - includes new and closed merge requests | ||
| - pushes - includes pushes | ||
| - issue_comments - includes new issue comments | ||
| - merge_request_comments - include new merge-request comments | ||
| - pipeline - include pipeline | ||
| - tag - include tag creation | ||
| - pull_reviews - includes merge request reviews | ||
| - label:"<labelname>" - must include "merges" or "issues" in feature list when using a label | ||
| - Defaults to "merges,issues,tag" | ||
|
|
||
|
|
||
|
|
||
|  | ||
|
|
||
|
|
||
|
|
||
| ### Personal Notifications: GitLab Bot | ||
|
|
||
| Each user in Mattermost is connected with their own personal GitLab account. Users can get a direct message in Mattermost when someone mentions them, requests their review, comments on, or modifies one of their merge requests/issues, or assigns them on GitLab. | ||
|
|
||
|
|
||
|
|
||
| ### Sidebar Buttons | ||
|
|
||
| Team members can stay up-to-date with how many reviews, unread messages, assignments, and open merge requests they have by using buttons in the Mattermost sidebar. | ||
|
|
||
|
|
||
|
|
||
| ## Mattermost Commands | ||
|
|
||
| Interact with the GitLab plugin using the `/gitlab` slash command. | ||
|
|
||
| ### Subscribe To/Unsubscribe From a Repository | ||
|
|
||
| Use `/gitlab subscribe owner[/repo] [features]` to subscribe a Mattermost channel to receive posts for new merge requests and/or issues, or other features (as listed above), from a GitLab repository. Ensure that the webhook is configured, otherwise this will not work properly. | ||
|
|
||
| Use `/gitlab unsubscribe owner/repo` to unsubscribe from it. | ||
|
|
||
| `/gitlab subscribe list` lists what you have subscribed to. | ||
|
|
||
| ### Connect To/Disconnect From GitLab | ||
|
|
||
| Connect your Mattermost account to your GitLab account using `/gitlab connect` and disconnect it using`/gitlab disconnect`. | ||
|
|
||
| `/gitlab me` displays the connected GitLab account. | ||
|
|
||
| ### Get "To Do" Items | ||
|
|
||
| Use `/gitlab todo` to get a list of unread messages and merge requests awaiting your review. | ||
|
|
||
| ### Update Settings | ||
|
|
||
| Use `/gitlab settings [setting] [value]` to update your settings for the plugin. There are two settings: | ||
|
|
||
| - To turn **personal notifications** `on` or `off. | ||
| - To turn **reminders** `on` or `off` for when you connect for the first time each day. | ||
|
|
||
| ### And More... | ||
|
|
||
| Run `/gitlab help` to see what else the slash command can do. | ||
|
|
||
|
|
||
|
|
||
| ## *Don't forget to add a webhook in GitLab* | ||
|
|
||
| See [Configuration](setup/configuration.md) |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,9 @@ | ||
| # Help and Support | ||
|
|
||
| For Mattermost customers - please open a [support case](https://mattermost.zendesk.com/hc/en-us/requests/new) to ensure your issue is tracked properly. | ||
|
|
||
| For Questions, suggestions, and help - please find us on our forum at [https://forum.mattermost.org/c/plugins](https://forum.mattermost.org/c/plugins). | ||
|
|
||
| Alternatively, join our public Mattermost server and join the [Integrations and Apps channel](https://community-daily.mattermost.com/core/channels/integrations). | ||
|
|
||
| To contribute to the Mattermost project see [https://www.mattermost.org/contribute-to-mattermost/](https://www.mattermost.org/contribute-to-mattermost/). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,42 @@ | ||
| # Configuration | ||
|
|
||
| ### Step 1: Register an OAuth application in GitLab | ||
|
|
||
| 1. Go to https://gitlab.com/profile/applications or https://gitlab.yourdomain.com/profile/applications to register an OAuth app. | ||
| 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 `https://your-mattermost-url.com` with your Mattermost URL | ||
| 3. Select `api` and `read_user` in **Scopes** | ||
| 4. Save the application | ||
| 5. Copy the **Application ID** and **Secret** fields from the resulting screen | ||
| 6. In Mattermost, go to **Plugins Marketplace > GitLab > Configure** | ||
| 7. Enter the **GitLab URL**, **GitLab OAuth Client ID**, and **Gitlab OAuth Client Secret** | ||
|
|
||
| ### Step 2: Configure Plugin in Mattermost | ||
|
|
||
| 1. Go to **Plugins Marketplace > GitLab** and click the **Configure** button or go to **System Console > Plugins > GitLab** and do the following: | ||
| 1. Generate a new value for `Webhook Secret` | ||
| 2. Generate a new value for **At Rest Encryption Key** | ||
| 3. (Optional) **GitLab Group**: Lock the plugin to a single GitLab group by setting this field to the name of your GitLab group. | ||
| 4. (Optional) **Enable Private Repositories**: Allow the plugin to receive notifications from private repositories by setting this value as `true`. When enabled, existing users must reconnect their accounts to gain access to a private project. Affected users will be notified by the plugin once private repositories are enabled. | ||
| 5. Click **Save**. | ||
| 2. Go to the top of the screen and set **Enable Plugin** to `True`and then click **Save** to enable the GitLab plugin. | ||
|
|
||
| ### Step 3: Configure Webhooks in GitLab | ||
|
|
||
| For each project you want to receive notifications for, or subscribe to, you must create a webhook. | ||
|
|
||
| 1. In GitLab, go to the project you want to subscribe to, select **Settings** then **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. | ||
| - **Secret Token**: the webhook secret you copied previously. | ||
| 3. Select all the events in **Triggers**. | ||
| 4. Add the webhook. | ||
|
|
||
| ### Step 4: Test it | ||
|
|
||
| To test it, run the `/gitlab connect` slash command to connect your Mattermost account with GitLab. | ||
|
|
||
|
|
||
|
|
||
| If you face issues installing the plugin, see our [Frequently Asked Questions]() for troubleshooting help, or open an issue in the [Mattermost Forum](http://forum.mattermost.org). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,24 @@ | ||
| --- | ||
| description: Get started by installing the GitLab plugin from the Marketplace | ||
| --- | ||
|
|
||
| # Installation | ||
|
|
||
| ### Release Dependency | ||
|
|
||
| * The GitLab plugin is included in the Plugin Marketplace in Mattermost v5.16 and above. | ||
| * For Mattermost v5.13 and earlier a manual install is necessary. | ||
|
|
||
| ### Marketplace Installation | ||
|
|
||
| 1. Go to **Main Menu > Plugin Marketplace** in Mattermost. | ||
| 2. Search for "gitlab" or manually find the plugin from the list and click **Install**. | ||
| 3. After the plugin has downloaded and been installed, click the **Configure** button. | ||
|
|
||
| ### Manual Installation | ||
|
|
||
| If your server doesn't have access to the internet, you can download the latest [plugin binary release](https://github.com/mattermost/mattermost-plugin-gitlab/releases) and upload it to your server via **System Console > Plugins > Plugin Management**. The releases on this page are the same used by the Marketplace. | ||
|
|
||
| See [documentation](https://docs.mattermost.com/administration/plugins.html#set-up-guide) for more details. | ||
|
|
||
| See [GitLab plugin release page](https://github.com/mattermost/mattermost-plugin-gitlab/releases) for compatibility considerations. |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,7 @@ | ||
| --- | ||
| description: Getting the latest features and fixes | ||
| --- | ||
|
|
||
| # Updating the Plugin | ||
|
|
||
| When a new version of the plugin is released to the **Plugin Marketplace**, the system will display a prompt asking you to update your current version of the GitLab plugin to the newest one. There may be a warning shown if there is a major version change that **may** affect the installation. Generally, updates are seamless and don't interrupt the user experience in Mattermost. |