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

Note

Homer can be installed by either manually cloning the git repository or by using the package provided. Check the deploy example to see how to deploy using the package.

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@20. 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}.

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

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 🎉

7. Configure releases

Releases management can be configured in config/homer/projects.json. Here is a sample configuration with one project:

{
  "projects": [
    {
      "description": "project_example",
      "notificationChannelIds": ["C0XXXXXXXXX"],
      "projectId": 1148,
      "releaseChannelId": "C0XXXXXXXXX",
      "releaseManager": "defaultReleaseManager",
      "releaseTagManager": "stableDateReleaseTagManager"
    }
  ]
}

8. Add your own release manager

A simple plugin system enables the addition of custom release managers. See this dedicated page for more details.

9. Examples

You can find some examples to add your own configuration, plugins and how to deploy.

Contributing

See CONTRIBUTING.md.