Gitlab: source management, CI & container repository platform

Starting as a source management platform, Gitlab has become a full DevOPS platform integrating CI and container repository functionnalities.

It also has integration possibilities with other tools for project management ( JIRA or Redmine ), source code management ( GitHub ), CI tools (AWS code pipeline, MockCI or Jenkins ) and many others.

• Official website: Gitlab
• Documentation: Gitlab documentation library
• Git source: Gitlab Community Edition

In this article, we'll cover the basics to set up a Gitlab platform accessible through HTTPS.

Gitlab on Ubuntu 22.04

Installing the proper package

After running your OS updates & upgrades, run the following commands:
sudo apt install -y ca-certificates curl openssh-server
curl -sS https://packages.gitlab.com/install/repositories/gitlab/gitlab-ce/script.deb.sh | sudo bash
sudo apt install gitlab-ce


The setup will run for a few minutes before you can see message thanking you for installing Gitlab:

To check that the service is running properly:

sudo systemctl status gitlab-runsvdir.service

First connection

Using your favorite browser, connect to your Gitlab:

• Username: root
• Passwprd: get the value set in
  sudo cat /etc/gitlab/initial_root_password

The file might say you could select the password by setting the parameter gitlab_rails['initial_root_password'] from the file "/etc/gitlab/gitlab.rb".
However this would not work in our current system.

Once logged in, don't forget to update the root password.

Best practive would be to create your own administrator user which isn't named root or admin.

Setting up HTTPS

If you're not using another solution to manage certificates such as Traefik, Gitlab can manage certificate renewal on it's own using Let's Encrypt.

Pre-requisite: make sure your server allows communication on port 80 and 443 for all servers for the Let's Encrypt challenge.

Update the configuration file:
sudo vi /etc/gitlab/gitlab.rb

Update the external_url value:
external_url 'https://gitlab.nicksopenworld.com'

Find the block "Let's Encrypt integration" and update it:

letsencrypt['enable'] =true
letsencrypt['contact_emails'] = ['some_email@nicksopenworld.com'] # This should be an array of email addresses to add as contacts

letsencrypt['auto_renew'] = true
letsencrypt['auto_renew_hour'] = "10"
letsencrypt['auto_renew_minute'] = "l5" # Should be a number or cron expression, if specified.
letsencrypt['auto_renew_day_of_month'] = "*/15"


Once the configuration file has been updated to your liking, reconfigure Gitlab:
sudo gitlab-ctl reconfigure

Once reconfiguration is finished, your server will be using HTTPS.

Email configuration

Update the GitLab email server settings block in the configuration file:
sudo vi /etc/gitlab/gitlab.rb

In the email settings block:

### Email Settings

# gitlab_rails['gitlab_email_enabled'] = true

##! If your SMTP server does not like the default 'From: gitlab@gitlab.example.com'
##! can change the 'From' with this setting.
# gitlab_rails['gitlab_email_from'] = 'example@example.com'
# gitlab_rails['gitlab_email_display_name'] = 'Example'
# gitlab_rails['gitlab_email_reply_to'] = 'noreply@example.com'
# gitlab_rails['gitlab_email_subject_suffix'] = ''
# gitlab_rails['gitlab_email_smime_enabled'] = false
# gitlab_rails['gitlab_email_smime_key_file'] = '/etc/gitlab/ssl/gitlab_smime.key'
# gitlab_rails['gitlab_email_smime_cert_file'] = '/etc/gitlab/ssl/gitlab_smime.crt'
# gitlab_rails['gitlab_email_smime_ca_certs_file'] = '/etc/gitlab/ssl/gitlab_smime_cas.crt'

Change values for gitlab_email_from and gitlab_email_reply_to to match the email(s) used in Gitlab.

SMTP configuration

In order to send notifications, email must be configured.
Gitlab can call on either a SMTP service on the local server or an external service.

Update the SMTP configuration:

### GitLab email server settings
###! Docs: https://docs.gitlab.com/omnibus/settings/smtp.html
###! Use smtp instead of sendmail/postfix.

# gitlab_rails['smtp_enable'] = true
# gitlab_rails['smtp_address'] = "smtp.server"
# gitlab_rails['smtp_port'] = 465
# gitlab_rails['smtp_user_name'] = "smtp user"
# gitlab_rails['smtp_password'] = "smtp password"
# gitlab_rails['smtp_domain'] = "example.com"
# gitlab_rails['smtp_authentication'] = "login"
# gitlab_rails['smtp_enable_starttls_auto'] = true
# gitlab_rails['smtp_tls'] = false
# gitlab_rails['smtp_pool'] = false

Check the SMTP settings format for the solution you want to use.

A working example with AWS SES

### GitLab email server settings
###! Docs: https://docs.gitlab.com/omnibus/settings/smtp.html
###! Use smtp instead of sendmail/postfix.

gitlab_rails['smtp_enable'] = true
gitlab_rails['smtp_address'] = "email-smtp.ap-south-1.amazonaws.com" 
gitlab_rails['smtp_port'] = 587
gitlab_rails['smtp_user_name'] = "AKIAQDS2TIGM6V3GRE4T" 
gitlab_rails['smtp_password'] = "J2EllDZgmFIlhj9CkRJuomFI7Ikk5SxbKaTd9AvO" 
gitlab_rails['smtp_domain'] = "smtp.nicksopenworld.com" 
gitlab_rails['smtp_authentication'] = "login" 
gitlab_rails['smtp_enable_starttls_auto'] = true
# gitlab_rails['smtp_tls'] = false

Incoming email configuration - Optional

General configuration

Emails can also be used to add comments if incoming email is configured.

Un-comment and configure the incoming email parameters:

Example of a working setup using a dedicated email server:

### Reply by email
###! Allow users to comment on issues and merge requests by replying to
###! notification emails.
###! Docs: https://docs.gitlab.com/ee/administration/reply_by_email.html
gitlab_rails['incoming_email_enabled'] = true

#### Incoming Email Address
####! The email address including the %{key} placeholder that will be replaced
####! to reference the item being replied to.
####! **The placeholder can be omitted but if present, it must appear in the
####!   "user" part of the address (before the @).**
# gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@nicksopenworld.com" #default structure
gitlab_rails['incoming_email_address'] = "%{key}@nicksopenworld.com" # Shortened email
# gitlab_rails['incoming_email_address'] = "gitlab@nicksopenworld.com" #If sub-addressing is not supported

#### Email account username
####! **With third party providers, this is usually the full email address.**
####! **With self-hosted email servers, this is usually the user part of the
####!   email address.**
# gitlab_rails['incoming_email_email'] = "gitlab@nicksopenworld.com"

#### Email account password
# gitlab_rails['incoming_email_password'] = "Gitlabemailpassword"
# gitlab_rails['incoming_email_password'] = "[REDACTED]"

#### IMAP Settings
gitlab_rails['incoming_email_host'] = "mail.nicksopenworld.com"
gitlab_rails['incoming_email_port'] = 993
gitlab_rails['incoming_email_ssl'] = true
# gitlab_rails['incoming_email_start_tls'] = false

#### Incoming Mailbox Settings (via mail_room)
####! The mailbox where incoming mail will end up. Usually "inbox".
gitlab_rails['incoming_email_mailbox_name'] = "inbox"
####! The IDLE command timeout.
gitlab_rails['incoming_email_idle_timeout'] = 60
####! The file name for internal mail_room JSON logfile
gitlab_rails['incoming_email_log_file'] = "/var/log/gitlab/mailroom/mail_room_json.log"
####! This marks incoming messages deleted after delivery.
####! If you are using Microsoft Graph API instead of IMAP, set this to false to retain
####! messages in the inbox since deleted messages are auto-expunged after some time.
gitlab_rails['incoming_email_delete_after_delivery'] = false
####! Permanently remove messages from the mailbox when they are marked as deleted after delivery
####! Only applies to IMAP. Microsoft Graph will auto-expunge any deleted messages.
# gitlab_rails['incoming_email_expunge_deleted'] = false

And in oder to not have credentials stored in an unsafe manner, the credentials have been encrypted (available in GitLab 15.9 or newer):

1. Comment out the following parameters in /etc/gitlab/gitlab.rb looked like:
   gitlab_rails['incoming_email_email'] = "gitlab@nicksopenworld.com"
gitlab_rails['incoming_email_password'] = "Gitlabemailpassword"


2. Edit the encrypted secret:
   sudo gitlab-rake gitlab:incoming_email:secret:edit EDITOR=vim

3. Update the values:
   user: 'gitlab@nicksopenworld.com'
password: 'Gitlabemailpassword'


4. Once all changes have been done, reconfigure Gitlab:
   sudo gitlab-ctl reconfigure

5. Test email import
   To make sure Gitlab can connect to the INBOX and import email, run the command line:
   sudo gitlab-rake gitlab:incoming_email:check

Notes on the gitlab_rails['incoming_email_address'] parameter

The value set for this parameter will depend on 2 elements
1 - does your email provider support sub-addresses ?
2 - how long can the email be ?

The "%{key}" will contain:

• Project's group
• Project's name/handle
• A gitlab token
• The type of object to create

For the examples below, a project "Project1" has been created in the group "Demo"

Examples:

• Default email structure
  Parameter:
  # gitlab_rails['incoming_email_address'] = "gitlab-incoming+%{key}@nicksopenworld.com" #default structure

Create issue by sending email at " gitlab-incoming+demo-project1-1-glimt-byd03blfkepy7aylguyszki9a-issue@nicksopenworld.com"

• Shortened email
  My email provider doesn't handle REGEX for email redirections so all emails need to be declared and have a 64 digit length limit so a shorter email format is required.
  gitlab_rails['incoming_email_address'] = "%{key}@nicksopenworld.com" # Shortened email


Create issue by sending email at "demo-project1-1-glimt-byd03blfkepy7aylguyszki9a-issue@nicksopenworld.com"

• When your email provider doesn't support sub-adresses
  gitlab_rails['incoming_email_address'] = "gitlab@nicksopenworld.com" #If sub-addressing is not supported

Create issue by sending email at "gitlab@nicksopenworld.com"
And the link "Email a new issue to this project" will not be present in the UI.

Email configuration in the UI to fine tune

A few settings can be changed directly in the UI via the administration Settings > Preferences > Email

Error management - Check that the information in config/gitlab.yml is correct

The "config/gitlab.yml" file is generated by the system when Gitlab is reconfigured using the command line:
sudo gitlab-ctl reconfigure

Therefore if you see this error, check your gitlab.rb configuration file:
sudo vi /etc/gitlab/gitlab.rb

Example: IMAP credentials are correct ? ... no

Cause: parameter gitlab_rails['incoming_email_mailbox_name'] hadn't been uncommented and set to "inbox".
Configuration file gitlab.rb was updated and Gitable reconfigured to correct the issue.

Conclusion

With the content of this article, you will have the bare minimum to have an accessible & usable platform that allows you to create a project and manage it either trough the UI or using emails.

It is by no mean a complete demonstration of all the capabilities of the system: user management through LDAP/SSO, container registry and other functionnalities will be adressed in dedicated articles.