GitLab Incubation Engineering - Service Desk, 16 Feb 2023

Previous Meeting Next Meeting

⏯

youtube image

►

From YouTube: How to set up mail_room and Service Desk in GDK

Description

This video is meant to provide a step by step introduction on how to set up mail_room, Incoming email and Service Desk email in GitLab Development Kit.

It should be suitable for both engineers and non engineers.

How to: https://gitlab.com/gitlab-org/gitlab-development-kit/-/blob/main/doc/howto/service_desk_mail_room.md

A

Hi, my name is Mark I'm, an incubation engineer at gitlab and I work on gitlab service desk and today, I want to show you how you can set up mail, room and service desk in your GDK.

A

There is um a how-to in our GDK doc, how-to folder and it's called service desk main room markdown, and there you can find all the steps that you need in order to get this up and running before we start I'm heading towards Point number. Five you need two email addresses I would recommend you use Gmail account because kind of everyone went through this and people know how to set it up properly and We. Know It supports all the things we need.

A

Please set up, two new Gmail accounts with whatever email address you come up with um enable two-factor and enter author, enable two-factor authentication and set up an app password for it. um You will need this because we want to access it via IMAP and um Gmail um discords using of those things. um So we need this password to make this work.

A

So just give you a minute: you can pause this video and create those email addresses and then come back to it and hit play again.

A

First of all, we stop all the Decay services, so you head over to your GDK I'm in the gitlab folder right now, so I go to the hdk folder and I run GDK stop.

A

So this is very important because we we overwrite settings and we install new things and we really need to stop it. The next thing, from some historical reason, we needed to fix the gitlab mailroom gem version to 0.0.9, um but to make this work we need a higher number and we need a higher version in this case. It's 21, maybe that it's 22 when you um when you watch this, but this does not matter. We just use 21 in this case and you will use whatever is the current version here.

A

So please, head over to your gem file in the gitlab folder ah I'm there, and there you see this dot, 9 version we use 21 here and that's kind of it. The next part is run bundle install in your gitlab folder in your terminal.

A

um This is important, so I really install that version so again go into your terminal, um go to the gitlab folder and then run bundle install. This might take a few seconds, but I have those things pre-installed. So it's quite fast.

A

The next thing is we need um so the ingestion works like this. We have mail room, a separate process. You will you will also need to run it separately, and the idea is that this mayroom process pause the inboxes that you just defined with your um with your app password, and we will also add this configuration later on um and we'll call it and every time it finds an unread new email.

A

It will take it and push it to the gitlab backend and to make this work, it uses a web hook mechanism via a internal API um and to make the authentication here we use a shared mailroom secret token, so we just generate one.

A

So, let's copy this, this will just generate a random number, um actually another number, but a random sequence of characters and write this to a hidden file called gitlab mailroom secret. You can do whatever you want with it rename it, but you need to take care you actually um at the correct path to it later. I would recommend you just leave it as is so back in the terminal.

A

You can just paste it. It's okay! It will always create that in your in your user's folder, if you want to take a look at it, so this is completely optional, but if you, if you feel like you, you want to take a look at it, you can just open it um and it's just some random stuff. So nothing fancy here.

A

So what do we need here? What do we need? Next? We need the full path to this secret file. If your system support reader path perfect, if it doesn't, you can use this. It will change to your home directory, but it will also print the complete path.

A

Maybe if you know your user and stuff like this, this will be okay, because you already know where it is, but we need that full path. In my case, it's slash, uses Amazon Echo and then the secret file. We need to copy this later on.

A

Okay, so now you have your email addresses um all set up and you have an email, an app password. We can head over to the next section, and this is kind of the configuration in our gitlab yaml file, where we actually tell gitlab hey. We want to use incoming email and we want to use service desk email sober, so we take this whole piece copy it and head over to our gitlab yaml file.

A

A

And when you access this, the first time you will see, there's some production section. You can just collapse it or scroll down until you reach the development section and please paste this here- some proper indentation because yellow cares.

A

um So what do we actually do here? We enable incoming email. This is important because otherwise we won't see those email addresses we can use and it won't. Actually the system won't support it.

A

um The next thing, let's assume you have your email address- is SuperDuper gmail.com. Then you would say super duper and then the plus and the key thing at gmail.com- and you would add- super duper gmail.com as the user then provide your fancy app password, which would look like this. Maybe um please let the delivery method stay at webhook. Gitlab URL should be fine if you use a domain name or something like this change that accordingly um and now, please add the real path of your secret file here.

A

So in my case, it's that, in your case, it might be something different. If you know your user, you can just replace your user with that here. That's also fine oops.

A

Okay, if you use gmam, those settings are perfectly fine. If you do not use Gmail, that might differ for the service desk email. Let's imagine you use service desk at gmail.com and then you would add the plus key notation here um service desk gmail.com as the user, your app password and kind of the same stuff. We did above.

A

So like this, and then you are set um to actually try this out, which is kind of cool, so it says, restart all services, and so let's do that. Get back to your gitlab development, kit, folder and run GDK starts foreign.

A

Here we are I just took a random project; it really doesn't matter because it's enabled by default for all projects.

A

um This is kind of polluted by my experimenting, so I just took that one here um head over to issues and service desk, and this is kind of your command control for service desk. And, if you, if you configure it correctly, you will see some some magic service desk email address here in my case, I use micro, dot, service desk gmail.com and it adds the path to the project plus the ID of the approach project plus issue, and the next thing I just mentioned.

A

uh Yeah I just mentioned that mailroom is a different process and we need to run it and that's true: um are you just a new terminal tab or a new terminal window? That's all perfectly fine! Just head over to your gitlab folder.

A

This is kind of the important thing here copy this one. It will actually use our GDK, no, not our GDK, but our gitlab yaml file settings because this file, the mailroom.yaml, is actually a dynamically generated configuration file from those settings, um but mailroom does not start rails and it does not start um a gitlab. So it's really kind of completely separate, but it uses the configuration from Gila.

A

So, let's copy that we installed the new versions, so everything everything should be fine, just paste it here and it will actually not print anything.

A

So we just know: okay, it kind of listens and it pulls every few seconds and checks for new um emails. Let's get back to our project, we have our email service, desk, email, address, I copy that and let's send an email.

A

Hello worlds: how are you doing.

A

We have a new issue.

A

So what actually is a service desk issue um on a code Wise It's defined by an issue where the author is the gitlab service bot, and we also have the email address of the issue here: yeah and it's sorry and it's confidential by default.

A

You will also see this in the list view. There's actually no difference here, but the service desk only lists service desk emails. So this is our service desk issues.

A

So when we write a comment on it, like hey I'm, fine.

A

um Then gitlab will send an email and because GDK has no setup for outcome emails. um We will find this in letter opener. So let's send this out refresh letter opener and there it is so. If you would like to answer to this one, you would need additional setup like really defining an SMTP connection on SMTP for sending out emails for GDK, which is also okay, but we won't cover this here. Maybe I do a second video on this one.

A

um So this is just the intake, um the intake side of things.

A

This is it um I hope you enjoyed the little how-to and you are set up and ready. If you encounter any difficulties, um please ping me or raise an issue um just ask someone who's familiar with service desk um yeah, so see you soon.