Homer is a Slack bot intended to help you to easily share and follow Gitlab merge requests.
At ManoMano, we were a bit tired of reading Gitlab emails to try keeping up to date with merge request updates.
Since we use Slack, we decided to create a bot that would help us to share our merge requests to other developers and to track their progress, so we could merge them more quickly:
Homer communicates with both Slack and Gitlab to get merge request information and publish Slack messages.
Here are the available commands:
Command | Description |
---|---|
/homer changelog |
Display changelogs, for any Gitlab project, between 2 release tags. |
/homer project add <project_name\|project_id> |
Add a Gitlab project to a channel. |
/homer project list |
List the Gitlab projects added to a channel. |
/homer project remove |
Remove a Gitlab project from a channel. |
/homer release |
Create a release for configured Gitlab project in a channel. |
/homer review <search> |
Share a merge request on a channel. Searches in title and description by default. Accepts merge request URLs and merge request IDs prefixed with "!". |
/homer review list |
List ongoing reviews shared in a channel. |
To share a merge request in a Slack channel using Homer, you have to follow the following steps:
To keep up to date the Slack messages it creates, Homer needs to be notified when something occurs on the related merge requests.
To do so, you need to set up a webhook in the Gitlab project of your merge request:
Ask for Homer's GITLAB_SECRET
to the person that manages Homer in your
organisation.
Go to the Webhooks
setting page of your Gitlab project.
Enter the following URL: HOMER_BASE_URL/api/v1/homer/gitlab
.
HOMER_BASE_URL
should also be provided by the person that manages Homer in
your organisation.
Enter the value of GITLAB_SECRET
in Secret token
field.
Check the following checkboxes: Push events
, Comments
,
Merge request events
.
Click on the Add webhook
button on the bottom of the page.
Make sure that the Gitlab user linked to your GITLAB_TOKEN
has at least the
Developer
role in your project:
Projects members
page:Use the search bar to find the information of the user.
Check that the role in Max role
is at least Developer
.
If it is the first time that you share a merge request of the Gitlab project in a Slack channel, you have to link them.
Inside the Slack channel, run one of the following commands:
/homer project add PROJECT_ID
/homer project add PROJECT_NAME
[!WARNING] If you want to use Homer in a private channel, you need to invite it to the channel first.
To share a Gitlab merge request to a Slack channel, use the
/homer review <search>
command.
You can provide a merge request ID prefixed with !
, e.g.: /homer review !128
.
If you want to get an overview of merge requests that are still being reviewed
(meaning they are not merged yet), use /homer review list
.
[!WARNING] Currently, Homer can only be installed by manually cloning the git repository.
Go to https://api.slack.com/apps/.
Click on Create New App
.
Select From an app manifest
.
Select the right workspace and click on Next
.
Copy the content of manifest.json file and paste it in the Slack webapp modal.
Create the app and enjoy.
Homer uses custom emojis when posting messages. To have them properly displayed, you will need to add all the emojis under emojis to your Slack organisation.
Be sure to have all those installed:
Create a .env
file containing the following variables:
API_BASE_PATH
This is the base path that will be used to build the API URL to call homer, for example https://homer.com<API_BASE_PATH>/command
.
GITLAB_SECRET
This is a user generated secret, so you can put any value.
It will be used later to set up Gitlab webhooks to allow Homer to verify that Gitlab→Homer calls are authentic.
GITLAB_TOKEN
If you don't already have one, you need to create a project access token on Gitlab by following the dedicated documentation.
This token allows Homer to use the Gitlab API.
SLACK_SIGNING_SECRET
Signin Secret
input in App credentials
section.This secret allows Homer to verify that Slack→Homer calls are authentic.
SLACK_BOT_USER_O_AUTH_ACCESS_TOKEN
OAuth & Permissions
in Features
menu.Bot User OAuth Token
.EMAIL_DOMAINS
Email domains of your organization (separated by comma),
for instance my-domain.com,ext.my-domain.com
.
Used to find Slack users from Gitlab username.
Note that this means your org has to use the same naming scheme for emails and gitlab username.
GITLAB_URL
The gitlab URL of your organization
TICKET_MANAGEMENT_URL_PATTERN
The ticket management URL pattern for your organization, this is used to generate a link to the ticket in the changelog.
It must contain the {ticketId}
matcher to be replaced by the ticket ID, for instance https://my-ticket-management.com/view/{ticketId}
.
SLACK_SUPPORT_CHANNEL_ID
This slack channel id is used to build a link displayed when a user enters the help command. People having trouble with Homer can be helped on this support channel.
SLACK_SUPPORT_CHANNEL_NAME
This slack channel name is displayed when a user enters the help command. People having trouble with Homer can be helped on this support channel.
If you want Homer to connect to an external PostgreSQL database, you can set the following variables:
POSTGRES_DATABASE_NAME
: database name (like homer
).POSTGRES_HOST
: host of the database.POSTGRES_PASSWORD
: password used when connecting to the database.POSTGRES_PORT
: port where the database listens.POSTGRES_USER
: username used when connecting to the database.# Clone the repo
git clone https://github.com/ManoManoTech/homer.git
# Go to directory that was just created
cd homer
# Install yarn dependencies
yarn install
# Start the database Docker container
docker compose up -d
# Build Homer
yarn build
# Start Homer
yarn start
To check that Homer is working properly, you can go to http://localhost:3000/api/monitoring/healthcheck and check that a donut is displayed.
On another terminal, open an HTTP bridge using ngrok:
npx ngrok http localhost:3000
.
Copy the Forwarding
URL (ex: https://d59a-176-179-182-210.ngrok.io
).
Go to the Slack apps page of your organisation.
Click on your app.
Click on Interactivity & Shortcuts
in Features
menu.
In Request URL
, replace https://HOMER_BASE_URL
by the URL you copied
above.
Click on Save Change
button.
Click on Slash Commands
in Features
menu.
Click on edit button.
In Request URL
, replace https://HOMER_BASE_URL
by the URL you copied
above.
Click on Save
button.
You should now be able to use Homer commands on Slack 🎉
See CONTRIBUTING.md.