manomanotech / homer

Homer is a Slack bot intended to help you to easily share and follow Gitlab merge requests.

Homer

Homer is a Slack bot intended to help you to easily share and follow Gitlab merge requests.

Why Homer?

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:

How does it work?

Homer communicates with both Slack and Gitlab to get merge request information and publish Slack messages.

Usage

Commands

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.

Share a merge request using Homer

To share a merge request in a Slack channel using Homer, you have to follow the following steps:

1. Make Homer notified of changes happening in the Gitlab project

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:

  • Go to the 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.

2. Add the Gitlab project to a Slack channel

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.

3. Share the merge request

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.

Install

Warning

Currently, Homer can only be installed by manually cloning the git repository.

1. Create the Slack app

• 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.

2. Add Slack emojis

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.

3. Prerequisites

Be sure to have all those installed:

• Docker Compose.
• Node.js@18. You can use a version manager like nvm.
• Yarn@1.

4. Set the necessary environment variables

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

  • Go to the Slack apps page of your organisation.

  • Click on your app.

  • Find 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

  • Go to the Slack apps page of your organisation.

  • Click on your app.

  • Click on OAuth & Permissions in Features menu.

    

  • Copy the 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}.

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.

5. Install and run

# 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.

6. Make your local instance of Homer reachable from outside

• 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 🎉

Contributing

See CONTRIBUTING.md.

homer's Issues

Open source the release and changelog feature

What

In the current Manomano internal project, homer offers the option of publishing and displaying a project's change log using the following commands :

• /homer changelog Generate changelogs for any Gitlab project using release tags.
• /homer release Create a Gitlab release.
• /homer release cancel Cancel a Gitlab release.
• /homer release end End a Gitlab release.

These functionalities should be reviewed and modified to make them available in the open-source project.

How

In order to add a releasable project, an internal configuration file must be modified. This behaviour needs to be reviewed to simplify the process and avoid the need to redeploy homer each time.

Firstly, we should externalise this configuration, and write documentation about it.
Then we could add a command like /homer release enable to register a new releaseable project.

The current configuration is as follows:

{
    notificationChannelIds: [
      IT_DEPLOY_CHANNEL_ID,
      FT_SELLER_CHANNEL_ID,
    ],
    projectId: 1,
    releaseChannelId: FT_SELLER_CHANNEL_ID,
    releaseManager: defaultReleaseManager,
    releaseTagManager: semanticReleaseTagManager,
  },

projectId : Gitlab project ID
notificationChannelIds : ID of the Slack channels that receive notifications about the release
releaseChannelId : ID of the slack channel where the release of the project is enabled
releaseManager : change depending on the type of the project (library, micro-service, frontend ..)
releaseTagManager : defines the tag naming (semantic, stable date ...)

The modal could be like this :

Update nodejs to latest LTS (20)

• Change engine here https://github.com/ManoManoTech/homer/blob/main/package.json#L19
• Test with node v20 (should work regarding the changelog)
• Fix if needed
• Update documentation https://github.com/ManoManoTech/homer?tab=readme-ov-file#3-prerequisites

Setup dependabot for github actions (and more?)

Here is an example on how to do so: https://github.com/doctrine/collections/blob/2.2.x/.github/dependabot.yml

Generate calendar

Not sure how feasible this is, but it might be nice to be able to generate a calendar (an ICS file) of the releases.

DB name is hardcoded

The database name is hardcoded.

How to fix:

• Use an environment variable instead.

GITLAB_URL not loaded properly

When using the docker image internally at my company, the GITLAB_URL does not seem to load properly.

Steps to reproduce on internal Gitlab:

• Pull image from GitHub and build another one in internal Gitlab.
• Run the image on Gitlab pipeline with all env variables set.

An error in log mentioning Environment variable GITLAB_URL not found

Add documentation about logging

The logging part to make homer production ready requires some documentation.
The code for logging is here

Reviewer Roulette

I've stumbled upon this project today and was wondering: wouldn't it be possible to implement mechanism for drawing reviewers? In larger teams it would be great if every member was involved at similar level, so this should draw reviewers considering review history and current activity. But MVP would be just ability to run command that would draw expected amount of reviewers.

List of users available for review should be configurable per project, as I don't see any reliable way based on available data (Slack channel's participant, Gitlab project's members would most probably be much wider than people interested in the MR), maybe CODEOWNERS would be closest.

What do you think?

Add default values for some env variables

POSTGRES_PORT=5432
POSTGRES_DATABASE_NAME=homer

Can we use homer with a node version > 18?

In the prerequisites you are talking about node 18.
Can we use a newer version of node?

Improve the current behaviour of fetching slack user from gitlab username

Currently
The rule is an exact match.

For example if the gitlab username is [email protected] it will try to find a slack user based exactly on this criteria. In some organization the conventions can be quite different between slack and gitlab.

Expected

This rule could be tweaked according to your need

Users email is hardcoded

Error message Failed to to fetch slack user with emails *** is displayed because it's hardcoded.
Line code

I can open an MR if you want