gitsy - Gitlab hubot for Rocket.Chat

Based on Hubot v3 ! Easy to customize with:

completely coffeescript free
full glitch.com support for rapid development
extend easily using modern ES6 async - await syntax

NOTE:

Edit files under scripts directory to customize your Hubot gitsy!

Quick Start

Get hubot-gitsy running on your Rocket.Chat and Gitlab server in 3 minutes.

Remix this glitch
edit the .env file and add information about your BOT, Rocket.Chat server, and Gitlab server (as documented in the Environment variables section below).

Linux Development/Deployment Quick Start

If you prefer development on a Linux system. You will need git and node installed.

Then check out the latest gitsy code:

git clone https://github.com/RocketChat/hubot-gitsy
cd hubot-gitsy
npm i

Add a .env file containing:

# note: .env is a shell file so there can't be spaces around =
ADAPTER_NAME=rocketchat
ROCKETCHAT_URL="https://your.rocketchat.server"
ROCKETCHAT_USESSL=true
ROCKETCHAT_USER="xxxx"
ROCKETCHAT_PASSWORD="xxxx"
ROCKETCHAT_ROOM="xxxxx"
RESPOND_TO_DM=true
RESPOND_TO_EDITED=true
GITLAB_API_KEY="xxxxx"
GITLAB_URL="https://your.gitlab.server/"
GITLAB_CHANNEL="xxxxx"
GITLAB_DEBUG="true"
GITLAB_BRANCHES="xxxxx"

(see Environment variables section for details on the variables)

Finally start gitsy:

npm start

Dockerized Quick Start

On a Linux / MacOS system with only docker installed. In an empty directory, checkout the latest gitsy code:

docker run -ti --rm -v ${HOME}:/root -v $(pwd):/git alpine/git clone https://github.com/RocketChat/hubot-gitsy
cd hubot-gitsy

Add a .env file containing:

# note: .env is a shell file so there can't be spaces around =
ADAPTER_NAME=rocketchat
ROCKETCHAT_URL="https://your.rocketchat.server"
ROCKETCHAT_USESSL=true
ROCKETCHAT_USER="xxxx"
ROCKETCHAT_PASSWORD="xxxx"
ROCKETCHAT_ROOM="xxxxx"
RESPOND_TO_DM=true
RESPOND_TO_EDITED=true
GITLAB_API_KEY="xxxxx"
GITLAB_URL="https://your.gitlab.server/"
GITLAB_CHANNEL="xxxxx"
GITLAB_DEBUG="true"
GITLAB_BRANCHES="xxxxx"

(see Environment variables section for details on the variables)

Then create a docker-compose.yml containing:

version: "2"
services:
  node:
    image: "node:8.11"
    user: "node"
    working_dir: /home/node/app
    environment:
      - NODE_ENV=development
    volumes:
      - ./:/home/node/app
    command: bash -c "npm install && npm start"

Finally, start gitsy as a daemon:

docker-compose up -d

Note the container name, and then you can watch the logs as the gitsy starts up:

docker logs <container name>

Environment variables

Gitsy is built on hubot-rocketchat and inherits environment variables. See https://github.com/RocketChat/hubot-rocketchat#configuring-your-bot

Env variable	Description
Hubot	A subset of relevant Hubot env vars
`HUBOT_ADAPTER`	Set to `rocketchat` (or pass as launch argument)
`HUBOT_NAME`	The programmatic name for listeners
`HUBOT_ALIAS`	An alternate name for the bot to respond to
`HUBOT_LOG_LEVEL`	The minimum level of logs to output
`HUBOT_HTTPD`	If the bot needs to listen to or make HTTP requests
Rocket.Chat SDK	A subset of relevant SDK env vars
`ROCKETCHAT_URL`*	Local Rocketchat address (start before the bot)
`ROCKETCHAT_USER`*	Name in the platform (bot user must be created first)
`ROCKETCHAT_PASSWORD`*	Matching the credentials setup in Rocket.Chat
`ROCKETCHAT_ROOM`	The default room/s for the bot to listen in to (csv)
`LISTEN_ON_ALL_PUBLIC`	Whether the bot should be listening everywhere
`RESPOND_TO_DM`	If the bot can respond privately or only in the open
`RESPOND_TO_EDITED`	If the bot should reply / re-reply to edited messages
`RESPOND_TO_LIVECHAT`	If the bot should respond in livechat rooms
`INTEGRATION_ID`	Name to ID source of messages in code (e.g Hubot)

* Required settings, unless running locally with testing defaults:

url: localhost:3000
username: bot
password: pass

ROCKETCHAT_USESSL may need to be set to true

In addition to those, Gitsy has its own

Env variable	Description
`GITLAB_URL`	The GitLab host that Gitsy will connect to.
`GITLAB_API_KEY`	Allow API access. Can be per account or per server.
`GITLAB_CHANNEL`	The channel where project events are posted.
`GITLAB_BRANCHES`	The branch(es) to monitor in a monitored project
`GITLAB_SHOW_COMMITS_LIST`	If the bot lists commits when commits are pushed
`GITLAB_SHOW_MERGE_DESCRIPTION`	If the bot's message includes the merge description

GITLAB_URL and GITLAB_API_KEY are necessary so Gitsy can talk to the Gitlab install.

GITLAB_URL is the GitLab host that Gitsy will connect to. It can be your own Community Edition server, or your projects on gitlab.com. If not set it defaults to gitlab.com.

GITLAB_API_KEY is the API key to allow Gitsy to access a GitLab account. If you are an administrator, you can get an API key for the entire server, with visibility to all projects; as a user, your API key can only access your own project(s). If not set only public projects are visible. If this is set but the key is invalid then Gitsy will throw an error. The API key can be created by going to your Gitlab profile, to Access Tokens and creating a personal access token.

GITLAB_CHANNEL is the channel in which messages about monitored projects are posted when events occur. Events include creation or modification of a PR, issue, branch, comment etc. It defaults to 'general' if not set.

GITLAB_BRANCHES specifies the branch or branches to monitor in a monitored project. It defaults to all.

GITLAB_SHOW_COMMITS_LIST tells the bot whether to list the commits pushed. It defaults to true. If set to false there will still be a message when commits are pushed but the commits will not be listed.

GITLAB_SHOW_MERGE_DESCRIPTION tells the bot whether to include the description when announcing a merge request. It defaults to true.

Gitlab integration, system and web hooks

There are two methods to using Gitsy. One way is to receive notifications from Gitlab as they come in and the other is to have Gitsy retrieve information on command.

Notifications sent from Gitlab

Gitlab → Bot → Channel

A system hook is used for receiving notifications in RocketChat from events in Gitlab such as creation of users or projects, commits etc. These notifications will appear in your chosen channel (GITLAB_CHANNEL) when something occurs in Gitlab. These notifications do not require GITLAB_URL or GITLAB_API_KEY to be set. Notifications can be set globally (system hooks) or per project (using web hooks).

Using system hooks

A system hook is used for events across Gitlab such as

Creation of a project
Deletion of a project
Creation of a user
Deletion of a user
A user having access to a project granted
A user having access to a project revoked

To set up a system hook in Gitlab go to the admin area and then to System Hooks.
The URL should be in the form: <bot url>/gitlab/system.
Triggers can be chosen and the system hook can be added.

Using web hooks

A web hook can be used to monitor events for specific projects. These events includes commits, issues, wiki pages etc.

To set up a web hook go to the project page, hover over settings and click integrations.
The URL should be in the form <bot url>/gitlab/web.
As with system hooks, triggers can be chosen and the web hook can be added.

Retrieving information from Gitlab

Channel → Bot → Gitlab

To retrieve information from Gitlab interactively, GITLAB_URL and GITLAB_API_KEY are necessary.

You can issue a command and Gitsy will query Gitlab and post a response back in the channel.

Commands include:

intro gitsy - gitsy introduces itself and lists available commands
projects - list all projects available
prs for n - list open merge requests for project #n
issues for n - list open issues for project #n
snippets for n - list snippets for project #n
pr n for m - show merge request #n for project #m
issue n for m - show issue #n for project #m
snippet n for m - view snippet #n for project #m

A couple of examples assuming your bot is named balti:

@balti intro gitsy

@<user> Hi, my name is gitsy, and I am the Rocket.Chat gitlab integration bot.
You can add me for your own Gitlab CE projects or Gitlab cloud public projects.
Find my code here:
https://github.com/RocketChat/Rocket.Chat.Ops/tree/master/hubots/hubot-gitsy
I can do webhooks, issues, merge requests, and snippets out of the box.
Please add to my abilities and contribute your code to Rocket.Chat.
projects - list all projects available
prs for n - list open merge requests for project #n
issues for n - list open issues for project #n
snippets for n - list snippets for project #n
pr n for m - show merge request #n for project #m
issue n for m - show issue #n for project #m
snippet n for m - view snippet #n for project #m

@balti projects

1       A project                     2018-11-29T12:41:24.240Z
2       another project               2018-09-17T21:04:33.967Z
3       a third project               2018-09-06T19:01:07.395Z

RocketChat / hubot-gitsy