Skip to main content

GitLab

Self-hosted GitLab CE for source control, CI/CD, and container registry.

Overview​

GitLab provides version control, CI/CD pipelines, and a container registry, integrated with Zitadel SSO for authentication.

PropertyValue
Imagegitlab/gitlab-ce:latest
Containergitlab
URLgitlab.ravenhelm.dev
SSH Port2222
Registryregistry.ravenhelm.dev
Data~/ravenhelm/data/gitlab/

Endpoints​

ServiceURLPurpose
Web UIhttps://gitlab.ravenhelm.devMain interface
APIhttps://gitlab.ravenhelm.dev/api/v4REST API
SSHssh://git@gitlab.ravenhelm.dev:2222Git SSH access
Container Registryhttps://registry.ravenhelm.devDocker images

SSO Integration​

GitLab uses Zitadel OIDC for single sign-on:

# /etc/gitlab/gitlab.rb
gitlab_rails["omniauth_enabled"] = true
gitlab_rails["omniauth_allow_single_sign_on"] = ["openid_connect"]
gitlab_rails["omniauth_auto_link_user"] = ["openid_connect"]

gitlab_rails["omniauth_providers"] = [
  {
    name: "openid_connect",
    label: "Zitadel",
    args: {
      scope: ["openid", "profile", "email"],
      issuer: "https://auth.ravenhelm.dev",
      discovery: true,
      client_options: {
        identifier: "351312537486163977",
        secret: "***",
        redirect_uri: "https://gitlab.ravenhelm.dev/users/auth/openid_connect/callback"
      }
    }
  }
]

Container Registry​

Push and pull Docker images:

# Login to registry
docker login registry.ravenhelm.dev

# Tag image
docker tag myapp:latest registry.ravenhelm.dev/username/myapp:latest

# Push
docker push registry.ravenhelm.dev/username/myapp:latest

# Pull
docker pull registry.ravenhelm.dev/username/myapp:latest

Git Configuration​

SSH Access​

# Clone via SSH (port 2222)
git clone ssh://git@gitlab.ravenhelm.dev:2222/username/repo.git

# Configure SSH
# ~/.ssh/config
Host gitlab.ravenhelm.dev
  Port 2222
  User git
  IdentityFile ~/.ssh/id_rsa

HTTPS Access​

# Clone via HTTPS
git clone https://gitlab.ravenhelm.dev/username/repo.git

# With personal access token
git clone https://username:glpat-TOKEN@gitlab.ravenhelm.dev/username/repo.git

Configuration​

Key Settings​

# /etc/gitlab/gitlab.rb

# External URL
external_url "https://gitlab.ravenhelm.dev"

# HTTPS handled by Traefik
nginx["listen_port"] = 80
nginx["listen_https"] = false
nginx["proxy_set_headers"] = {
  "X-Forwarded-Proto" => "https",
  "X-Forwarded-Ssl" => "on"
}

# Container Registry
registry_external_url "https://registry.ravenhelm.dev"
registry["enable"] = true
registry_nginx["listen_port"] = 5050
registry_nginx["listen_https"] = false

# SSH Port
gitlab_rails["gitlab_shell_ssh_port"] = 2222

# Performance (M4 Pro)
puma["worker_processes"] = 2
sidekiq["concurrency"] = 10

# Disable unused features
prometheus_monitoring["enable"] = false
gitlab_pages["enable"] = false

Quick Commands​

# View logs
docker logs -f gitlab

# Restart GitLab
docker restart gitlab

# GitLab Rails console
docker exec -it gitlab gitlab-rails console

# Check GitLab status
docker exec -it gitlab gitlab-ctl status

# Reconfigure GitLab
docker exec -it gitlab gitlab-ctl reconfigure

# Check version
docker exec -it gitlab cat /opt/gitlab/embedded/service/gitlab-rails/VERSION

Backup & Restore​

Backup​

# Create backup
docker exec -t gitlab gitlab-backup create

# Backup location
ls ~/ravenhelm/data/gitlab/data/backups/

Restore​

# Stop services
docker exec -it gitlab gitlab-ctl stop puma
docker exec -it gitlab gitlab-ctl stop sidekiq

# Restore
docker exec -it gitlab gitlab-backup restore BACKUP=timestamp

# Restart
docker restart gitlab

Troubleshooting​

502 Bad Gateway​

Symptoms: GitLab returns 502 after restart

Cause: GitLab takes 2-5 minutes to fully start

Resolution:

# Wait and check logs
docker logs -f gitlab

# Check internal health
docker exec -it gitlab gitlab-ctl status

Registry Push Fails​

Symptoms: denied: access forbidden when pushing

Resolution:

  1. Verify logged in: docker login registry.ravenhelm.dev
  2. Check project visibility settings
  3. Verify registry is enabled in project settings

OIDC Login Fails​

Symptoms: SSO login redirects but fails

Resolution:

  1. Check Zitadel app redirect URI
  2. Verify client ID/secret in gitlab.rb
  3. Check GitLab logs: docker logs gitlab | grep -i oidc

References​