Hubot is "chat bot" created by GitHub that listens for commands and executes actions based on your requests.
hubot-matteruser is a Hubot adapter for Mattermost written in JavaScript that uses the Mattermost Web Services API and WebSockets to deliver Hubot functionality.
- Learn more about Hubot in Wired Magazine
- Learn more about Mattermost as an open source, self-hosted team communication server
This Hubot adapter connects to your Mattermost server. You can invite your bot to any channel just as a regular user. It listens and perform your commands. The adapter uses mattermost-client for all low level Mattermost communication.
Two authentication methods are supported:
- login/password,
- personnal access token.
The second one is necessary if the Mattermost server delegates the authentication to another service (for example when using Mattermost shiped with GitLab). Such method is also probably prefered as the token does not reveals original credentials and can be revoked without any impact on the related account.
Clone this repository, then build the Hubot-Matteruser container:
$ docker build --build-arg hubot_owner=<owner> \
--build-arg hubot_name=<name> \
--build-arg hubot_description=<desc> \
--tag=hubot-matteruser \
.
Start the container:
$ docker run -it \
--env MATTERMOST_HOST=<mm_host> \
--env MATTERMOST_GROUP=<mm_team> \
--env MATTERMOST_USER=<mm_user_email> \
--env MATTERMOST_PASSWORD=<mm_user_password> \
-p 8080:8080 \
--name hubot-matteruser \
hubot-matteruser
or if you have a personal access token:
$ docker run -it \
--env MATTERMOST_HOST=<mm_host> \
--env MATTERMOST_GROUP=<mm_team> \
--env MATTERMOST_ACCESS_TOKEN=<personal>
-p 8080:8080 \
--name hubot-matteruser \
hubot-matteruser
To integrate with a running Mattermost instance, update docker-compose.yml accordingly and launch the bot:
docker-compose build
docker-compose run -d
If you just want to test locally, you can find here a fork of the official Mattermost Docker Compose stack plugged to Hubot-Matteruser:
Follow the Mattermost install guides to set up the latest version of Mattermost 5.4.x.
IMPORTANT: Make sure your hubot-matteruser and mattermost-client versions match the major version of your Mattermost server so the API versions will match.
On a separate server, install hubot-matteruser using the following commands:
npm install -g yo generator-hubot
yo hubot --adapter matteruserFollow the instructions to set up your bot, including setup of mattermost-client.
The adapter requires the following environment variables to be defined before your Hubot instance will start:
| Variable | Required | Description |
|---|---|---|
| MATTERMOST_HOST | Yes | The Mattermost host e.g. mm.yourcompany.com |
| MATTERMOST_GROUP | Yes | The team/group on your Mattermost server e.g. core |
| MATTERMOST_USER | No | The Mattermost user account name e.g. hubot@yourcompany.com |
| MATTERMOST_PASSWORD | No | The password of the user e.g. s3cr3tP@ssw0rd! |
| MATTERMOST_ACCESS_TOKEN | No | The personal access token of the user |
| MATTERMOST_WSS_PORT | No | Overrides the default port 443 for websocket (wss://) connections |
| MATTERMOST_HTTP_PORT | No | Overrides the default port (80 or 443) for http:// or https:// connections |
| MATTERMOST_TLS_VERIFY | No | (default: true) set to 'false' to allow connections when certs can not be verified (ex: self-signed, internal CA, ... - MITM risks) |
| MATTERMOST_USE_TLS | No | (default: true) set to 'false' to switch to http/ws protocols |
| MATTERMOST_LOG_LEVEL | No | (default: info) set log level (also: debug, ...) |
| MATTERMOST_REPLY | No | (default: true) set to 'false' to stop posting reply responses as comments |
| MATTERMOST_IGNORE_USERS | No | (default: empty) Enter a comma-separated list of user senderi_names to ignore. |
The below example assumes you have created a user hubot@yourcompany.com with username hubot and password s3cr3tP@ssw0rd! on your Mattermost server in the core team reachable on URL https://mm.yourcompany.com/core
export MATTERMOST_HOST=mm.yourcompany.com
export MATTERMOST_GROUP=core
export MATTERMOST_USER=hubot@yourcompany.com
export MATTERMOST_PASSWORD=s3cr3tP@ssw0rd!To upgrade your Hubot for Mattermost 4.4.x, find the package.json file in your Hubot directory and look for the line in the dependencies section that references hubot-matteruser. Change the verion so it points to ^5.4.4 of the client. Example:
...
"dependencies": {
"hubot-matteruser": "^5.4.6"
},
...You can try out Hubot by joining the Mattermost community server and joining the Hubot channel:
- Create an account on the Mattermost nightly builds server at https://pre-release.mattermost.com/
- Join the "Hubot" channel
- Type
hubot helpfor instructions
You can try a simple command like hubot the rules to bring some static text stored in Hubot:
Try hubot animate me to have Hubot reach out to Giphy and bring back a random animated image.
Try hubot map me [NAME_OF_CITY] to have Hubot reach out to Google Maps and bring back a map based on the name of a city you pass in as a parameter. For example, hubot map me palo alto brings back the below map of Palo Alto
The MIT License. See LICENSE file.