-
Notifications
You must be signed in to change notification settings - Fork 16
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Feature/25176 bitbucket readme #125
Open
kat-kan
wants to merge
10
commits into
mattermost-community:master
Choose a base branch
from
kat-kan:feature/25176-bitbucket-readme
base: master
Could not load branches
Branch not found: {{ refName }}
Loading
Could not load tags
Nothing to show
Loading
Are you sure you want to change the base?
Some commits from the old base branch may be removed from the timeline,
and old review comments may become outdated.
Open
Changes from all commits
Commits
Show all changes
10 commits
Select commit
Hold shift + click to select a range
9d24874
Move assets to new directory (docs/images). Update project files with…
kat-kan d478ad4
Update README.md
kat-kan f71ced3
Organize admin-guide.md
kat-kan e3e30cd
Remove Marketplace from admin-guide as requested in CR
kat-kan f51bbd9
Remove empty headlines from README and admin-guide
kat-kan 6f73c7d
Revert "Move assets to new directory (docs/images). Update project fi…
kat-kan 764c498
Remove code coverage badge as agreed in CR
kat-kan b0518f7
Adjust Admin Guide section as requested in CR
kat-kan 29bf6d4
Adjust Help Wanted as requested in CR
kat-kan 644bc1f
Merge branch 'master' into feature/25176-bitbucket-readme
mattermost-build File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
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,97 @@ | ||
| # Admin guide | ||
|
|
||
| This guide is intended for Mattermost System Admins setting up the Bitbucket plugin and Mattermost users who want information about the plugin functionality. For more information about contributing to this plugin, visit the Development section. The Mattermost Bitbucket plugin uses a webhook to connect your Bitbucket account to Mattermost to listen for incoming Bitbucket events. Events notifications are via Direct Message in Mattermost. The Events don’t need separate configuration. | ||
|
|
||
| - [Prerequsites](#prerequisites) | ||
| - [Installation](#installation) | ||
| - [Manual](#manual) | ||
| - [Configuration](#configuration) | ||
| - [Onboard Users](#onboard-users) | ||
|
|
||
| ## Prerequisites | ||
|
|
||
| This guide assumes: | ||
|
|
||
| - You have a Bitbucket account. | ||
| - You're a Mattermost System Admin. | ||
| - You're running Mattermost Server v5.25 or higher. | ||
|
|
||
| ## Installation | ||
|
|
||
| ### Manual | ||
|
|
||
| If your server doesn't have access to the internet, you can download the latest [plugin binary release](https://github.com/mattermost/mattermost-plugin-bitbucket/releases) and upload it to your server via **System Console > Plugin Management**. The releases on this page are the same used by the Marketplace. To learn more about how to upload a plugin, see [the documentation](https://developers.mattermost.com/integrate/plugins/using-and-managing-plugins/). | ||
|
|
||
| ## Configuration | ||
|
|
||
| Configuration is started in Bitbucket and completed in Mattermost. | ||
|
|
||
| ### Step 1: Register an OAuth application in Bitbucket | ||
|
|
||
| 1. Go to [https://bitbucket.org](https://bitbucket.org) and log in. | ||
| 2. From your profile avatar in the bottom left, select the workspace in the **Recent workspaces** list or select **All workspaces** for a full list. | ||
| - Select **Settings** in the left sidebar to open the workspace settings. | ||
| - Under **Apps and features**, select **OAuth consumers**. | ||
| 3. Select **Add consumer** and set the following values: | ||
| - **Name:** `Mattermost Bitbucket Plugin - <your company name>`. | ||
| - **Callback URL:** `https://your-mattermost-url.com/plugins/bitbucket/oauth/complete`, replacing `https://your-mattermost-url.com` with your Mattermost deployment's Site URL. | ||
| - URL: [https://github.com/mattermost/mattermost-plugin-bitbucket](https://github.com/mattermost/mattermost-plugin-bitbucket). | ||
| 4. Set: | ||
| - **Account:** `Email` and `Read` permissions. | ||
| - **Projects:** `Read` permission. | ||
| - **Repositories:** `Read` and `Write` permissions. | ||
| - **Pull requests:** `Read permission`. | ||
| - **Issues:** `Read` and `Write` permissions. | ||
| 5. Save the **Key** and **Secret** in the resulting screen. | ||
| 6. Go to **System Console > Plugins > Bitbucket** | ||
| 7. Enter the Bitbucket **OAuth Client ID** and **Bitbucket OAuth Client Secret** you copied in a previous step. | ||
| 8. Select **Save**. | ||
|
|
||
| ### Step 2: Create a webhook in Bitbucket | ||
|
|
||
| You must create a webhook for each repository you want to receive notifications for or subscribe to. | ||
|
|
||
| 1. Go to the **Repository settings** page of the Bitbucket organization you want to send notifications from, then select **Webhooks** in the sidebar. | ||
| 2. Select **Add Webhook**. | ||
| 3. Set the following values: | ||
| - **Title:** `Mattermost Bitbucket Webhook - <repository_name>`, replacing `repository_name` with the name of your repository. | ||
| - **URL:** `https://your-mattermost-url.com/plugins/bitbucket/webhook?secret=SOME_SECRET` | ||
| - replace `https://your-mattermost-url.com` with your Mattermost deployment's Site URL. | ||
| - replace `SOME_SECRET` with the secret generated in System Console > Plugins > Bitbucket > Webhook Secret. | ||
| 4. Select **Choose from a full list of triggers**. | ||
| 5. Select: | ||
| - **Repository:** `Push`. | ||
| - **Pull Request:** `Created`, `Updated`, `Approved`, `Approval removed`, `Merged`, `Declined`, `Comment created`. | ||
| - **Issue:** `Created`, `Updated`, `Comment created`. | ||
| 6. Select **Save**. | ||
|
|
||
| If you have multiple repositories, repeat the process to create a webhook for each repository. | ||
|
|
||
| ### Step 3: Configure the plugin in Mattermost | ||
|
|
||
| If you have an existing Mattermost user account with the name `bitbucket`, the plugin will post using the `bitbucket` account but without a BOT tag. | ||
|
|
||
| To prevent this, either: | ||
|
|
||
| Convert the `bitbucket` user to a bot account by running `mattermost user convert bitbucket --bot` in the CLI. | ||
|
|
||
| or | ||
|
|
||
| If the user is an existing user account you want to preserve, change its username and restart the Mattermost server. Once restarted, the plugin will create a bot account with the name `bitbucket`. | ||
|
|
||
| ### Generate a key | ||
|
|
||
| Open **System Console > Plugins > Bitbucket** and do the following: | ||
|
|
||
| 1. Generate a new value for **At Rest Encryption Key**. | ||
| 2. \(Optional\) **Bitbucket Organization:** Lock the plugin to a single Bitbucket organization by setting this field to the name of your Bitbucket organization. | ||
| 3. Select **Save**. | ||
| 4. Go to **System Console > Plugins > Management** and select **Enable** to enable the Bitbucket plugin. | ||
|
|
||
| You're all set! | ||
|
|
||
| ## Onboard users | ||
|
|
||
| When you’ve tested the plugin and confirmed it’s working, notify your team so they can connect their Bitbucket account to Mattermost and get started. Copy and paste the text below, edit it to suit your requirements, and send it out. | ||
|
|
||
| > Hi team, We've set up the Mattermost Bitbucket plugin, so you can get notifications in Mattermost. To get started, run the `/bitbucket connect` slash command from any channel within Mattermost to connect your Mattermost and Bitbucket accounts. Then, take a look at the slash commands section for details about how to use the plugin. |
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Can we instead have the image committed to this repo?