Andrew Wegner | Ponderings of an Andy - gitlab

How to fix GitLab 18 error regarding git_data_dirs

2025-07-06T08:00:00-05:00

Introduction¶

Several years ago I set up GitLab in my home environment. I appreciate past me documenting the basic steps I took to do this, because I'll need them again at some point when I make upgrades to my home lab. I've documented some things I've done (like setting up GitLab runners, or dealing with Grafana being deprecated within GitLab or utilizing GitLab to automatically backup my Obsidian notes) Unfortunately, I didn't document everything. One of those things that I didn't document was changing where my repositories are stored on disk by default.

In GitLab 17.8 (January 2025), a new deprecation warning started appearing.

git_data_dirs has been deprecated since 17.8 and will be removed in 18.0. See https://docs.gitlab.com/omnibus/settings/configuration.html#migrating-from-git_data_dirs for migration instructions.

I'm a little annoyed that there were only 5 months of notice on this because major versions are released in May. In any case, if you attempt to update to version 18 or beyond and are utilizing git_data_dirs, the upgrade will fail.

Solution¶

As usual, GitLab is good at providing documentation on resolving and migrating through the deprecations. However, on my first attempt I encountered an error. I believe it's because I missed a note buried in the text - not the code blocks - the first time.

Note that the /repositories suffix must be appended to the path because it was previously appended internally.

The solution is to open /etc/gitlab/gitlab.rb (you probably should make a backup first). Find the git_data_dirs line. For me this was around line 455. Then comment out this entire block.

Then find (or add) the gitaly['configuration'] block. This was immediately after the git_data_dirs section for me. Uncomment it, and add the appropriate path (from your git_data_dirs block) and add /repositories to the end of it.

Once you are done, run

gitlab-ctl reconfigure
gitlab-ctl restart

Give it a minute to fire up all the GitLab subcomponents, and then you should be able to update GitLab beyond version 18.

New code section¶

My gitlab.rb now has this:

#git_data_dirs({
#  "default" => {
#    "path" => "/previous/path/to/repos"
#   }
#})

### Gitaly settings
gitaly['configuration'] = {
storage: [
    {
    name: 'default',
    path: '/previous/path/to/repos/repositories',
    },
],
}

Conclusion¶

With this quick change, I can continue to hold the repositories at a location of my choosing. The biggest thing is to add /repositories to the path in the new Gitaly configuration. With this change, I can continue to utilize the current version of GitLab - a tool that I still find invaluable.

Syncing Obsidian Notes across devices using Git and GitLab

2023-09-26T13:30:00-05:00

Introduction¶

I take a lot of notes. About five years ago I switched from utilizing notebooks, because I was going through them so quickly, to a Rocket Book. This feels very similar to a notebook, with the benefit that it is reusable. It also has an application that allows me to quickly scan a page and save it to one of several locations. It's very handy. The downside is that the OCR isn't perfect (oooor, my handwriting is bad) and the annoyance of cleaning the pages every week or so. I've found that if I don't let the pages dry completely, then the next time I go to use that page it has a fine film over it that makes writing a little more difficult. Think writing with a pen that is low on ink.

I discovered Obsidian a while ago. I've put a little bit of effort into utilizing it, but more recently I've committed to utilizing it more. The idea of all digital notes is enticing. Over time I'll see if it's helpful.

But, like anyone with multiple devices, I want my Obsidian vault on all devices. What if I have a thought while I'm away from my main computer? One option is to utilize the Obsidian Sync feature. It's got end to end encryption, version history and a monthly subscription fee. I can build something using my existing GitLab installation without that monthly subscription fee. Plus, since I'm the only user of this, I'm ok with a little trade off that a full service provides.

Repository Setup¶

GitLab¶

Within GitLab set up a new project by clicking on "New Project" in the upper right.

Select the option to create a new blank project.

Now we need to set up the project details. Select a name that is meaningful for you. I've utilized andy-notes in the screenshot below. I also created this without a README, because I'll generate the initial repository in a moment and push it up to the server.

Repository Initialization¶

This set of steps only has to occur once. All devices will be able to start with the next section.

Open the command prompt or terminal (depending on what your operating system calls the system console). Navigate to the location you want your notes to be stored. In my case, I created a new directory to match the name of my repository. I then created a .gitignore with the following content in the directory.

.obsidian/*
!.obsidian/app.json
!.obsidian/appearance.json
!.obsidian/config
!.obsidian/community-plugins.json
!.obsidian/core-plugins.json
!.obsidian/graph.json
!.obsidian/hotkeys.json

This should ignore the majority of the .obsidian hidden directory between my devices, but keep a few key items. I may update this over time, but for now this is working well.

Now, initialize the repository.

cd andy-notes
git init --initial-branch=main
git remote add origin git@<my.server.url>:andy/andy-notes.git
git add .
git commit -m "Initial Commit"
git push --set-upstream origin main

We're ready to start utilizing Obsidian and GitLab!

Obsidian Setup¶

First Open¶

Now that the backend repository is set up and it's been initially configured, all instances of Obsidian can utilize these sets of steps to start working.

If this is not the device you initialized the repository on, you need to perform an initial pull of the repository to this device so that it is a local folder.

git clone git@<my.server.url>:andy/andy-notes.git

Open Obsidian. Since this is the first time you are opening it, you'll be asked to select where your vault is stored. You want to select the "Open folder as vault" option.

Select the location that your repository has been cloned into.

Enable Plugins¶

Obsidian has support for community built plugins. There are plugins to do all kinds of things to improve your writing and note taking. I encourage the reader to look through or search for plugins that may help you. We, however, need one specific one to accomplish our goal of syncing the vault over to GitLab.

Obsidian Git

To install community plugins we need to enable this feature. In the lower left of the workspace, click the gears icon. Then click on "Community plugins", and finally "Turn on community plugins"

With this enabled, you can now browse the community plugins. To do so, click the browse button.

Search for Obsidian Git. While writing this, it was the first result. You should be looking for the one by Vinzent. Click on the card to pull up plugin details and potential actions.

Then click "Install". The installation process should only take a moment or two.

You'll receive a confirmation in the upper right if the install is successful.

Finally, enable the new plugin. The previous "install" button has changed to be "Enable". Click that.

Configure Obsidian Git¶

With the Obsidian Git plugin installed, it's time to configure it. There are a few quick settings to fill out. First, you need to click the "Options" button.

The first setting to change is how often you want the backup to GitLab to occur. This automatic back up is disabled by default. I set mine to be every 5 minutes.

Next, enable Pull updates on startup so that the instance of Obsidian that is running is always up to date. Your notes from other devices will be synchronized when Obsidian launches and you can get right back to writing.

Be sure to add the Author name and email address. This is the information that will be sent on each commit.

I also adjusted the autocommit message to include the hostname of the device performing the commit. I have been going back and forth on whether this is important enough for me to keep since I'm the only one that utilizes this vault. But, if you want to adjust the messages there are two instances where the commit message can be modified.

Results¶

After performing the steps above, this instance of Obsidian is ready to utilize GitLab to sync your vault for free. Each new instance only needs to have the Obsidian Git plugin installed, enabled and configured.

After you've configured your instance, when you open Obsidian the plugin will pull changes from the repository and let you know that everything has been updated.

Then on a scheduled basis - 5 minutes in my case - it will commit and push changes to GitLab.

In GitLab, this commit should show up immediately.

Conclusion¶

I now have Obsidian set up on my main devices. I've enjoyed the ability to have my notes available as soon as I open the application. Overall, this was pretty easy to set up. It seems like a lot of steps, but the one time setup makes it much longer than installing and configuring a plugin for each new instance actually takes.

I'm trying to keep my notes digital and I'm hopeful that this new set up will help. I can move between computers for personal projects instead of wondering what I had found in my research because I left it on another tab on another machine and forgot to put it with the rest of my notes. Now, it just happens.

How to disable Grafana in Gitlab 16.3 Omnibus

2023-08-23T22:15:00-05:00

Introduction¶

I continue to love my self hosted instance of GitLab. I look forward to the 22nd of every month to pull down the newest dot update and enjoy the new features. As with any piece of software, things get deprecated and eventually disabled over time.

In 16.3 - released in August 2023 - the version of Grafana bundled with the self hosted version of GitLab reached the end of its deprecation window and was disabled. GitLab added a check to prevent an update if it was still enabled.

Symptom¶

When performing an apt update, GitLab 16.3 will error out if Grafana is still enabled on your instance. The error looks like this:

Preparing to unpack .../gitlab-ee_16.3.0-ee.0_amd64.deb ...
* grafana[enable] has been deprecated since 16.0 and was removed in 16.3. The bundled Grafana is deprecated and no longer available. We recommond following
https://docs.gitlab.com/ee/administration/monitoring/performance/grafana_configuration.html#deprecation.
Deprecations found. Please correct them and try again.

The Problem¶

The documentation linked provides four steps to follow

To switch away from bundled Grafana to a newer version of Grafana from Grafana Labs:

Set up a version of Grafana from Grafana Labs.

Export the existing dashboards from bundled Grafana.

Import the existing dashboards in the new Grafana instance.

Configure GitLab to use the new Grafana instance.

I've removed the links in steps 2 and 3, because they really don't matter for this write up. Step 1 does not have a link, so it's left as an exercise to the user to install Grafana in their environment. Step 4, links to another article that provides a few more steps to follow.

On the left sidebar, expand the top-most chevron.

Select Admin Area.

On the left sidebar, select Settings > Metrics and profiling and expand Metrics - Grafana.

Select the Add a link to Grafana checkbox.

Configure the Grafana URL. Enter the full URL of the Grafana instance.

Select Save changes.

And that's it. That's the set of instructions provided by GitLab. Follow those, rerun your apt update and you'll run into the same symptom.

Solution¶

The missing step is hinted at in the error message itself: grafana[enable] has been deprecated

This is a setting in the GitLab configuration file. You will need to edit the config file and set the value to false.

Edit /etc/gitlab/gitlab.rb (or appropriate path)

Edit the grafana[enable] value to be false. On my config this was on line 1689, but I recommend you search for the string grafana to find it.

grafana['enable'] = false

Reconfigure GitLab by running gitlab-ctl reconfigure. Let this run and it should end with gitlab Reconfigured!

You can now resume the apt update that failed due to having Grafana enabled.

Once done, you will get the standard GitLab upgrade complete message and you'll be good to go.

Reading unsupported config value grafana.¶

Update: July 2024, GitLab 17.1

In the GitLab 17.1 update from June 2024, Grafana has been completely removed. If you still have grafana keys in the config file upon updating to 17.1, the upgrade will fail with

Mixlib::config::unknownconfigoptionerror: Reading unsupported config value grafana.

The solution to this is to edit /etc/gitlab/gitlab.rb and comment out (or remove entirely) all lines that start with grafana. Once this is done, save the file and attempt the upgrade again. Like when it was originally deprecated, this step will end with gitlab Reconfigured.

Review of GitLab's 'TeamOps Certification' course

2023-02-02T23:00:00-06:00

Introduction¶

A little over two years ago, I took GitLab's course on how to manage a remote team. That was a very useful course and I was able to apply several best practices from that course to my role at the time, plus roles I've held since then. I continue to manage global and remote teams, so I was excited to hear about GitLab's newest course covering their "TeamOps" model of improving teams.

This course is hosted on LevelUp, and is one of 9 public courses they have available right now.

Course Overview¶

The TeamOps Certification course is split into 5 sections and covers about 2-3 hours of material.

The first section covers the foundations of TeamOps
The remaining four sections cover the 4 guiding principles of TeamOps
- Shared Reality
- Everyone Contributes
- Decision Velocity
- Measurement Clarity

Except for the welcome message in the first lesson, this course is entirely text based. I was surprised by this because of the previous course from GitLab and the extensive use of video on how to manage a remote team. This course does have a 6-7 question knowledge check at the end of each section and will not let you proceed if you score below an 80%.

Fortunately, the questions are easy - assuming you comprehend what you are reading and not just clicking through to the next page. The course also provides access to the updated The Remote Playbook, which is a great starting point for checking your company's remote processes.

TeamOps felt like a good extension and refresher from the "How to Manage a Remote Team" course. Unfortunately, that's all it felt like - a refresher.

Conclusion¶

The change from video to text based courses was surprising, and slightly unwelcome. The content of the course is good, and will definitely help teams improve how they operate. However, many of the same ideas were covered in the previous course. I suppose that if this continues to work for GitLab, it makes sense that they aren't trying to make sweeping changes, but I was hoping for...more, I suppose.

I recommend this course to anyone who manages a team remotely and needs a refresher from the previous course GitLab provided or doesn't have the recommended 11 hours for that course. This should take about an hour and a half to read through. If, however, you have more time I think the "How to Manage a Remote Team" course course has even more information that will be helpful.

Review of GitLab's 'How to Manage a Remote Team' Coursera course

2020-10-26T09:30:00-05:00

Introduction¶

I am a huge fan of GitLab - both the product and the company. As the largest all remote workforce, they are in an enviable position of being an expert on how to manage a team of over 1000 global employees without having an office. My current position puts me in charge of managing a global, remote, workforce as well but on a smaller scale.

When GitLab announced they were releasing a course on How to Manage a Remote Team on Coursera, I jumped at the opportunity to take it. I want to expand my skill set as a manager of remote employees and the chance to learn some best practices from GitLab in this area was a good place to start.

Course Overview¶

The course is split up in to a four week set of lessons and covers about 11-12 hours of material.

Week 1 covers Remote Best Practices.
Week 2 covers Managing Remote Teams.
Week 3 covers Remote Adaption Processes for Organizations
Week 4 covers Culture and Values for Distributed Teams

The final task then is building a remote transition plan for an organization.

Overall, these were well done. The videos are presented by various GitLab employees and cover a variety of different aspects in each section. There are various readings assigned too. These provide a ton of information, especially The Remote Playbook.

There is some GitLab centric information provided and back patting, but it is done in a way that helps to show why certain things are needed - like open and transparent documentation. By the end of the course, you will know that GitLab has an open handbook for everyone to read and you will know why you should as well. This type of thing is expected and knowing that the instructors will do some back patting is important too.

The final project - building a remote transition plan - is peer reviewed. You are presented with a series of questions, which you answer with a short essay for each and using information presented during the course. When you are done, the last task you have is to peer review three of your cohort's projects.

Conclusion¶

This course was information dense and useful. The time estimate is off as the videos take only about an hour each week. Either I am a faster reader than I thought or they have overestimated the time it would take to read the weekly material. In either case, I estimate that I spent about 6 hours. It was also nice that, although the course is split into weeks, everything is available immediately upon completing the previous tasks.

I recommend this course to anyone who manages a team remotely or who is in the process of transitioning to remote work. COVID has given the entire world a crash course in remote work, but this course is a good way to handle and manage those newly remote workers effectively. It is also a good course to take if your company is planning on extending the work remote environment that 2020 has thrust upon you to last beyond this current pandemic.

GitLab has done a good job with this course.

Setting up GitLab runners

2019-10-22T11:00:00-05:00

Introduction¶

It's been a year and a half since I set up GitLab. In that time I've used it to store my personal code, keep track of features I want to add to my own projects, and generally loved it. One thing I haven't done though, is play with the CI/CD features. I've been wanting to, but never got around to it.

To utilize the CI/CD features, you need to set up a GitLab runner

Set up¶

Docker¶

I'll be running my runners in Docker containers. There are other options, but for my home environment, this is easiest to set up and maintain.

Let's start by installing Docker:

sudo apt-get install apt-transport-https ca-certificates curl software-properties-common -y
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable"
sudo apt update
sudo apt install docker-ce -y

This is going to add the Docker repository and install the community edition.

GitLab Runner¶

Once Docker is installed and working, we can install the GitLab runner.

wget -O /usr/local/bin/gitlab-runner https://gitlab-runner-downloads.s3.amazonaws.com/latest/binaries/gitlab-runner-linux-amd64
chmod +x /usr/local/bin/gitlab-runner
useradd --comment 'GitLab Runner' --create-home gitlab-runner --shell /bin/bash
gitlab-runner install --user=gitlab-runner --working-directory=/home/gitlab-runner
gitlab-runner start

This is downloading the install package. Then it adds a new user, that the runner will run as. This is a nice security precaution to limit what the runner has access to on the system. It's not full security, but it does allow me to restrict what that particular user has access to on the server.

Then the runner is started.

Next the runner needs to be registered. Log into GitLab, and navigate to the project that will be using this runner. It should be available at this link:

https://url.to.your.gitlab.install/<account>/<repo>/settings/ci_cd

Grab the GitLab CI token. That is needed in the next step. Run the gitlab-runner register command, and fill in your values as required.

$ gitlab-runner register
Please enter the gitlab-ci coordinator URL (e.g. https://gitlab.com/):
https://url.to.your.gitlab.install/

Please enter the gitlab-ci token for this runner:
[redacted]]

Please enter the gitlab-ci description for this runner:
[my-runner]: python-runner

Please enter the gitlab-ci tags for this runner (comma separated):
python
Registering runner... succeeded                     runner=66m_339h

Please enter the executor: docker-ssh+machine, docker, docker-ssh, parallels, shell, ssh, virtualbox, docker+machine, kubernetes:
docker

Please enter the default Docker image (e.g. ruby:2.1):
alpine:latest

Runner registered successfully. Feel free to start it, but if it's running already the config should be automatically reloaded!

My experience with Docker is limited, so I am using the latest alpine version. I'm sure there are better ones to use for a simple Python application, but this works for me and I'm not concerned about the absolute fastest CI/CD pipeline on my server.

Using the CI/CD pipeline¶

At this point, the GitLab runner is registered to a single project and is ready to use. You can enable your project to use this pipeline by adding a .gitlab-ci.yml file to the root of your repository.

I used it to set up the following pipeline.

This pipeline has 4 stages.

Static Analysis¶

In the Static Analysis phase, I run various analysis tools over my code. The goal here is to ensure that my code, YAML documents, and documentation are easy to read and use.

You'll notice the xenon task has a warning in the image. I have the settings pretty strict in this pipeline, where I allow a very low Cyclomatic Complexity. In this project, I have one function that is just barely failing my strict settings. I have allowed the pipeline to continue if this one particular task fails.

I could either increase the allowed complexity in the code base to ignore the warning. Alternatively, I could not allow the pipeline to proceed until I fix this function. This was one of those instances where it hasn't been worth it to refactor the code, but I want to be reminded I should fix it, so I allow the pipeline to proceed and show me the error.

Test¶

The Test phase should be fairly self explanatory. It's the stage where I run my test suite. It will only run if the Static Analysis phase completes successfully (or I allow a specific job to fail, in the case of the xenon task).

Deploy Testing¶

Once the test suite has completed successfully, I deploy the package to the test instance of PyPI. This ensures that I have a successful build and deploy.

Deploy Production¶

Deployment to production is a manual step. I did this because I don't always want to push changes to production PyPI. This is especially true if I'm only making small fixes - such as white space changes. I don't want to skip the entire CI process, but I also don't want to push out to production for something so minor.

Environment set up¶

One of my biggest complaints about the Travis CI integration with GitHub is how you can't trust environment variables in Travis CI. Since I control the server that this runner is connected to, I have no problem adding environment variables into GitLab.

In the project, I was able to add these by going to Settings->CI/CD and expanding the Variables section. I needed to store credentials for both the test and production instances of PyPI.

With these added, they are now accessible by my .gitlab-ci.yml file.

.gitlab-ci.yml¶

The script I use to build the pipeline is as follows:

image: "python:3.7"

.python-tag:
  tags:
    - python

before_script:
  - python --version
  - pip install .[dev]

stages:
  - Static Analysis
  - Test
  - Deploy Testing
  - Deploy Production

flake8:
  stage: Static Analysis
  extends:
    - .python-tag
  script:
    - flake8 --max-line-length=120

doc8:
  stage: Static Analysis
  extends:
    - .python-tag
  allow_failure: true
  script:
    - doc8 --max-line-length=100 --ignore-path=docs/_build/* docs/

yamllint:
  stage: Static Analysis
  extends:
    - .python-tag
  allow_failure: true
  script:
    - yamllint .

bandit:
  stage: Static Analysis
  extends:
    - .python-tag
  allow_failure: true
  script:
    - bandit -r -s B101 my_package

radon:
  stage: Static Analysis
  extends:
    - .python-tag
  script:
    - radon cc my_package/ -s -a -nb
    - radon mi my_package/ -s -nb

xenon:
  stage: Static Analysis
  extends:
    - .python-tag
  allow_failure: true
  script:
    - xenon --max-absolute B --max-modules B --max-average B my_package/

pytest:
  stage: Test
  extends:
    - .python-tag
  script:
    - pytest

deploy_testing:
  stage: Deploy Testing
  extends:
    - .python-tag
  variables:
    TWINE_USERNAME: $PYPI_TEST_USERNAME
    TWINE_PASSWORD: $PYPI_TEST_PASSWORD
  script:
    - python setup.py sdist
    - twine upload --repository-url $PYPI_TEST_URL dist/*

deploy_production:
  stage: Deploy Production
  extends:
    - .python-tag
  when: manual
  variables:
    TWINE_USERNAME: $PYPI_PROD_USERNAME
    TWINE_PASSWORD: $PYPI_PROD_PASSWORD
  script:
    - python setup.py sdist
    - twine upload dist/*

.gitlab-ci.yml explanation¶

There are a few areas that I feel need to be explained in the script above.

Tags¶

.python-tag:
  tags:
    - python

This section is a template that is used to add the python tag to a job step. The Runner will only run tasks that have a tag you assigned to it. This is useful if you are building across multiple operating systems or across multiple languages. You don't want a runner set up to test against a Windows environment picking up tasks for a Linux environment. In my case, everything is being run for a single runner.

In each step, I need to add this:

extends:
  - .python-tag

With this, the python tag will be automatically applied to the task. For a simple pipeline like mine, it may seem like overkill, but it's useful if I want to force other tags or steps.

Allow failures¶

xenon:
  stage: Static Analysis
  extends:
    - .python-tag
  allow_failure: true
  script:
    - xenon --max-absolute B --max-modules B --max-average B my_package/

I previously mentioned that I allowed the xenon step to fail. This is accomplished with the allow_failure: true setting you see here. Since this setting is in place, the pipeline will proceed even if this single task fails.

Manual deployment¶

deploy_production:
  stage: Deploy Production
  extends:
    - .python-tag
  when: manual
  variables:
    TWINE_USERNAME: $PYPI_PROD_USERNAME
    TWINE_PASSWORD: $PYPI_PROD_PASSWORD
  script:
    - python setup.py sdist
    - twine upload dist/*

The deploy to production is a manual step. I use when: manual to ensure this step doesn't occur automatically. At some point in the future, this project will be stable and won't have minor fixes any longer and I'll want to automatically deploy to production without interaction. When I reach that point, I'll just need to remove this line. As long as the preceding steps succeed, this one will be performed as well.

Next Steps¶

Now that I've set this up and come to rely on it, I think my next steps will be converting my home Minecraft Server to use the GitLab pipelines to automatically deploy updates. Look for that post in the future.

Setting up GitLab on the new server

2018-04-13T08:30:00-05:00

Introduction¶

Back when I ran Vipers, my fellow admins and I hosted a small set of code repositories - SVN, Mercurial and Git - to host some of our custom code. We ran RhodeCode and the fork, Kallithea, when RhodeCode closed sourced some of its code and couldn't figure out if the license it used actually allowed themselves to do that. A private repository was awesome for plugins, server configurations and personal projects.

When the community was shuttered, some of the plugin code was migrated to GitHub and it's sat there untouched since. My personal projects were either migrated to GitHub or simply stored outside of version control if it couldn't go in a public repository. That was less than ideal, but it worked. With the new home server set up, I wanted to get source control set back up for my non-public personal projects.

I rejected RhodeCode right away due to the experiences I had when they changed licenses. Turns out, they had done it again in the meantime. I didn't want to deal with that. I attempted to install Kallithea using their instructions, but I kept running into Python syntax errors. It wasn't worth the time and effort to figure out the problem.

So, I turned to GitLab. It's definitely overkill for what I really need, but it works and if I ever truly decide to get fancy, I have a lot of other tools I can use. The core functionality is what I'll be using and is free. The three other versions cost some money and contain features that would be useful for large teams, not a single developer or very small team.

Installation¶

Dependencies¶

Installing GitLab is pretty simple. There are a couple dependencies needed, but I already had both OpenSSH and Postfix installed, so I was able to skip the first step in the official installation guide. I installed the Ubuntu Omnibus package.

sudo apt-get install -y curl openssh-server ca-certificates postfix

Getting the package¶

The GitLab repository needs to be added and then installed. To add the repository, issue this command:

curl https://packages.gitlab.com/install/repositories/gitlab/gitlab-ee/script.deb.sh | sudo bash

To install the GitLab package, you need to provide an environment variable when you issue your apt-get install command. This will be the URL where you want to access your GitLab installation.

sudo EXTERNAL_URL="http://gitlab.example.com" apt-get install gitlab-ee

Complete the installation¶

Once the install, above is complete, you need to log in to complete the process. In your browser, navigate to the URL you provided above. Set/reset the password as prompted and then login.

Post-install Tweaks¶

Using Apache instead of Nginx¶

The omnibus package comes with Nginx bundled. Unfortunately, I don't have any experience managing an Nginx instance but do have experience with Apache. I want to use something that I know to make my life easier. Fortunately, GitLab can handle this with a few minor changes to the configuration.

In the /etc/gitlab/gitlab.rb file you'll need to make several settings changes. You also need Apache already installed and the www-data user (on Ubuntu) added to the gitlab-www group.

Find nginx['enable'] and set it to false
In web_server['external_users'], add www-data to the array. Note that this is an array and not a single string.
In gitlab_rails['trusted_proxies'], add the IP address of the Apache web server.
Change the gitlab workhorse settings to the following (default) values.

These may already be in the configuration file. If so, you probably don't need to modify them.

gitlab_workhorse['listen_network'] = "tcp"
gitlab_workhorse['listen_addr'] = "127.0.0.1:8181"

Finally, run sudo gitlab-ctl reconfigure for the settings to take effect.

Now, you need to configure Apache's virtual host. GitLab provides example virtual hosts. Since I installed the omnibus package and am using Apache 2.4, I selected the gitlab-omnibus-apache24.conf file. Adjust all instances of YOUR_SERVER_FQDN to the fully qualified domain name of your server.

This will go in /etc/apache2/sites-available/ and a symlink in /etc/apache2/sites-enabled/ will point to this file.

sudo touch /etc/apache2/sites-available/gitlab.conf
sudo ln -s /etc/apache2/sites-available/gitlab.conf /etc/apache2/sites-enabled/gitlab.conf

Use SSL to access GitLab¶

The example virtual host provided by GitLab uses HTTP only. I want to set up my instance to use HTTPS. I'll be doing this with Let's Encrypt, like I did when I set up NextCloud in the previous post. I cover the exact steps for Let's Encrypt in another post. The keys referenced in the virtual host configuration file below were created by that process.

The first change to make is to redirect the HTTP version of your domain to HTTPS. The goal is that all traffic to GitLab will go over SSL. Adjust the ServerName variable as appropriate.

<VirtualHost *:80>
  ServerName gitlab.example.com
  ServerSignature Off

  RewriteEngine on
  RewriteCond %{HTTPS} !=on
  RewriteRule .* https://%{SERVER_NAME}%{REQUEST_URI} [NE,R,L]
</VirtualHost>

Then, everything in the sample virtual host file can be put in the <VirtualHost *:443> block.

At the top of this block, we need to reference the Let's Encrypt keys:

SSLProtocol all -SSLv2
SSLHonorCipherOrder on
SSLCipherSuite "ECDH+AESGCM:DH+AESGCM:ECDH+AES256:DH+AES256:ECDH+AES128:DH+AES:ECDH+3DES:DH+3DES:RSA+AESGCM:RSA+AES:RSA+3DES:!aNULL:!MD5:!DSS"
Header add Strict-Transport-Security: "max-age=15768000;includeSubdomains"
SSLCompression Off
SSLCertificateFile /path/to/dehydrated/certs/gitlab.example.com/cert.pem
SSLCertificateKeyFile /path/to/dehydrated/certs/gitlab.example.com/privkey.pem
SSLCertificateChainFile /path/to/dehydrated/certs/gitlab.example.com/chain.pem

Save and restart Apache. You should be automatically redirected over HTTPS when you visit your GitLab URL.

Allow spaces in repository names¶

One of the only problems I ran into with GitLab is that, by default, repositories with spaces in them can't be viewed in the web browser. It throws a 400 Bad Request when trying to view the directory. There is a bug report regarding this problem. The developers are working on updating the samples in a way that is guaranteed to work through the whole system.

For me, though, the first comment which suggests a minor RewireRule change works great. In the virtual host, find the line

RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA,NE]

and remove the NE so that it reads

RewriteRule .* http://127.0.0.1:8181%{REQUEST_URI} [P,QSA]

Restart Apache and you can navigate to the directory with a space.

Setting up SMTP¶

GitLab can send out emails and requires the ability to do so when resetting a password, at minimum. I don't want this email to be marked as spam, so I used one of the free providers from here and set up an account. After editing the /etc/gitlab/gitlab.rb file to match the provider I selected, I ran gitlab-ctl reconfigure. Now any emails GitLab sends out goes through the trusted email provider instead of coming directly from my residential IP address. This means my mail provider trusts it. I also send out less than 5 emails a month currently, so I am well below the tier where I lose my "free" status.

Conclusion¶

At this point, GitLab is set up over SSL on my server. I can log in and start setting up repositories. Migrating and importing the code bases I didn't want to put on a public GitHub account was very satisfying. Maybe I'll look into some of the more advanced features GitLab offers in the near future, but for the time being I'm happy with what I have and the knowledge that I can expand what I do with GitLab.