GitLab Runner offline after upgrade to GitLab 17.5 ($HOME is not defined)

If your GitLab Runner is marked as offline after upgrading to GitLab 17.5 (CE or EE), an adjustment of the environment configuration of the GitLab service is required because the environment variable $HOME cannot be found. The problem arises because a non-existent environment configuration file is configured in the Systemd service provided by GitLab.

Extract from the GitLab Systemd Service:

# [...]

Restart=always
RestartSec=120

EnvironmentFile=-/etc/sysconfig/gitlab-runner

# [...]

Error message

journalctl -f -u gitlab-runner.service

gitlab-runner[1191]: FATAL: failed to get user home dir: $HOME is not defined
ystemd[1]: gitlab-runner.service: Main process exited, code=exited, status=1/FAILURE

Troubleshooting

If you encounter the error, the following adjustment is required on the GitLab runner via shell:

# Create sysconfig directory (if not exists)
mkdir -p /etc/sysconfig

# Define $HOME variable for gitlab-runner service
echo "HOME=/home/gitlab-runner" >> /etc/sysconfig/gitlab-runner

# Restart GitLab Runner Service
systemctl restart gitlab-runner

# Verify GitLab Runner Service Status
systemctl status gitlab-runner

Alternatively, you can execute all commands at the same time:

mkdir -p /etc/sysconfig && \
echo "HOME=/home/gitlab-runner" >> /etc/sysconfig/gitlab-runner && \
systemctl restart gitlab-runner && \
systemctl status gitlab-runner

The GitLab service is then marked as active (running) again:

If you still have difficulties with your GitLab-Runner despite the adjustment, please contact our Support directly so that we can help you solve the problem as quickly as possible.

Sources

Interested in managed GitLab hosting?

Migrate your self-managed GitLab instance to our managed GitLab server solutions with our free migration service. 14-day free trial available.