egeneralov.gitlab

Provision GitLab Omnibus (CE/EE) on Debian/Ubuntu with LDAP, OmniAuth (OIDC/OAuth2), optional S3 backups, and an optional custom nginx mTLS edge.

Target package: GitLab CE 18.11.3-ce.0 (override with gitlab_version).

Requirements

• Ansible >= 2.14
• Debian bullseye/bookworm or Ubuntu jammy/noble
• Open ports 80/443 yourself (this role does not manage iptables/nftables/firewalld)

Role Variables

Required

Variable	Notes
domain	e.g. gitlab.example.com
registry_host	e.g. registry.example.com
email	Let's Encrypt / notifications
root_password	>= 8 chars (initial root only)
runners_token	Legacy shared runners registration token (bootstrap). Prefer runner authentication tokens on GitLab 16+.

Version / package

• gitlab_version — default 18.11.3-ce.0 (always pinned; no silent latest)
• gitlab_revision — ce or ee
• gitlab_key_url / gitlab_keyring_path — apt signed-by keyring

LDAP

See defaults/main.yml (ldap.*). Prefer encryption: start_tls or simple_tls with verify_certificates: true and ca_file.

OmniAuth (GitLab 18)

Providers use Omnibus shape: name + optional label + nested args / client_options.

Flags (optional): allow_single_sign_on, block_auto_created_users, auto_link_user, auto_link_ldap_user, auto_sign_in_with_provider.

Dex (OIDC)

Register a static client in Dex (e.g. infrastructure/networking/dex) with redirect
https://<domain>/users/auth/openid_connect/callback.

omniauth:
  enabled: true
  allow_single_sign_on: ["openid_connect"]
  block_auto_created_users: false
  auto_link_user: ["openid_connect"]
  providers:
    - name: openid_connect
      label: Dex
      args:
        name: openid_connect
        scope: ["openid", "profile", "email"]
        response_type: code
        issuer: https://dex.generalov.org
        discovery: true
        client_auth_method: query
        uid_field: preferred_username
        pkce: true
        client_options:
          identifier: gitlab
          secret: "{{ vault_gitlab_dex_secret }}"
          redirect_uri: "https://{{ domain }}/users/auth/openid_connect/callback"

GitHub

omniauth:
  enabled: true
  allow_single_sign_on: ["github"]
  providers:
    - name: github
      app_id: "{{ vault_github_app_id }}"
      app_secret: "{{ vault_github_app_secret }}"
      args:
        scope: "user:email"

Google

omniauth:
  enabled: true
  allow_single_sign_on: ["google_oauth2"]
  providers:
    - name: google_oauth2
      app_id: "{{ vault_google_client_id }}"
      app_secret: "{{ vault_google_client_secret }}"

Other provider names are passed through to gitlab.rb with a warning if unknown.

Backup (S3 / Spaces)

backup:
  enabled: true
  bucket: "gitlab-backups"
  schedule: daily
  upload_connection:
    provider: AWS
    region: ams3
    aws_access_key_id: "..."
    aws_secret_access_key: "..."
    endpoint: "https://ams3.digitaloceanspaces.com"

Restore

restore:
  enabled: true
  from: 1710000000_2026_03_01_18.11.3_gitlab_backup.tar
  secrets: gitlab-secrets.json   # optional but recommended
  force: false

Stops puma + sidekiq, then gitlab-rake gitlab:backup:restore.

Let's Encrypt (Omnibus nginx)

letsencrypt:
  enable: true
  contact_emails:
    - noc@example.com

Uses top-level Omnibus letsencrypt['…'] keys. Set external_url to HTTPS via letsencrypt.enable or custom nginx.

Nginx modes

1. Omnibus nginx (default): nginx.enable: true, custom_nginx.enable: false
2. Custom nginx edge (mTLS / whitelist): nginx.enable: false, custom_nginx.enable: true

Custom edge fronts workhorse (unix:/var/opt/gitlab/gitlab-workhorse/sockets/socket) and registry (127.0.0.1:5000).
Firewall for 80/443 is not managed by this role.

nginx:
  enable: false
custom_nginx:
  enable: true
  whitelist:
    - 192.168.0.0/24
  ssl:
    provider: selfsigned
    users: []

For trusted reverse proxies with Omnibus nginx, use raw_config:

raw_config: |
  gitlab_rails['trusted_proxies'] = ['10.0.0.0/8']

Prometheus

Bundled Grafana was removed in GitLab 16.3 — this role no longer emits grafana keys.

Example Playbooks

Install (Omnibus nginx)

- hosts: gitlab
  vars:
    domain: gitlab.example.com
    registry_host: registry.example.com
    email: noc@example.com
    root_password: "{{ vault_gitlab_root }}"
    runners_token: "{{ vault_gitlab_runners_token }}"
    gitlab_version: 18.11.3-ce.0
  roles:
    - egeneralov.gitlab

Custom nginx + mTLS CA

- hosts: gitlab
  vars:
    domain: gitlab.example.com
    registry_host: registry.example.com
    email: noc@example.com
    root_password: "{{ vault_gitlab_root }}"
    runners_token: "{{ vault_gitlab_runners_token }}"
    nginx:
      enable: false
    custom_nginx:
      enable: true
      ssl:
        provider: selfsigned
        base_subj: "/C=NL/ST=lab/L=lab/O=lab/OU=lab"
        users: []
  roles:
    - egeneralov.gitlab

Client certs (manual): generate CSR, sign with /etc/gitlab/ssl/ca.{crt,key}, import PFX on the client.

LDAP + S3 backup

- hosts: gitlab
  vars:
    domain: gitlab.company.tld
    registry_host: registry.company.tld
    email: noc@company.tld
    root_password: "{{ vault_gitlab_root }}"
    runners_token: "{{ vault_gitlab_runners_token }}"
    ldap:
      enabled: true
      host: ldap.company.tld
      bind_dn: 'uid=gitlabro,ou=svcaccts,dc=company,dc=tld'
      password: "{{ vault_ldap_bind }}"
      encryption: start_tls
      base: 'dc=company,dc=tld'
      user_filter: '(objectClass=inetorgperson)'
    backup:
      enabled: true
      bucket: gitlab-company-tld-backup
      upload_connection:
        provider: AWS
        region: ams3
        aws_access_key_id: "{{ vault_s3_key }}"
        aws_secret_access_key: "{{ vault_s3_secret }}"
        endpoint: https://ams3.digitaloceanspaces.com
  roles:
    - egeneralov.gitlab

License

MIT