GitLab Configurations with File Configuration

Some of Configurations and Opstella Integrations are done through Ruby Configuration File on the GitLab Machine at OS-level.

Configuration Prerequisites

• 🔑OpenID Connect Credentials: Client ID, Client Secret.
  • Your dedicated Keycloak Realm. foobar-opstella ; Please change accordingly
  • Gather Client ID, Client Secret - from Procuring Keycloak Credentials

Preparation

You are about to perform on a Virtual Machine that play a role to be GitLab instance.

💡 Before proceed, Make sure you are connected to the GitLab Instance in any way possible, i.e SSH, Privileged Access Management Console, etc.

Place TLS Certificate Files

Remarks

This is assume that you DO NOT HAVE any system that automatically rotate TLS Certificates for you.

You need to copy TLS Certificate Files on to GitLab Instance by following the instructions below.

Assume TLS Certificate for *.${BASE_DOMAIN} to associate with gitlab.${BASE_DOMAIN}

• Public Key Certificate wildcard-${BASE_DOMAIN}.crt
• Private Key Certificate wildcard-${BASE_DOMAIN}.key

You need to place TLS Certificate Files in the GitLab Configuration Directory like this.

• Directory/

  • Directoryetc

    • Directorygitlab

      • Directoryssl

        • wildcard-BASE_DOMAIN.crt
        • wildcard-BASE_DOMAIN.key

1. Create Directory /etc/gitlab/ssl/ (typically not existed)

   sudo mkdir -p /etc/gitlab/ssl

2. Store TLS Certificate on path /etc/gitlab/ssl/

   sudo cp wildcard-${BASE_DOMAIN}.crt /etc/gitlab/ssl/
   sudo cp wildcard-${BASE_DOMAIN}.key /etc/gitlab/ssl/

3. Apply Appropriate File Permission

   sudo chmod 400 -R /etc/gitlab/ssl/*.key
   sudo chmod 400 -R /etc/gitlab/ssl/*.crt

---

gitlab.rb Configuration File

Edit file /etc/gitlab/gitlab.rb

# Backup original configuration file, this also can be use as configuration references
sudo mv /etc/gitlab/gitlab.rb /etc/gitlab/gitlab.rb.orig

This will guide you to configure the following with GitLab configuration file

• GitLab Basic Configurations
  • URL through which GitLab will be accessed. ; Strict Requirement from GitLab.
  • Enable TLS Certificate to GitLab Instance.
    • Use TLS Certificate files installed from the previous section.
  • Enable Prometheus Metrics Exporter
• Opstella Integration: Clear Session Services Redirection
• Opstella Integration: Single Sign-On
  • Create/Gather Client ID, Client Secret from Procuring Keycloak Credentials

Need Other Settings?

See: https://gitlab.com/gitlab-org/omnibus-gitlab/blob/master/README.md#changing-gitlab-yml-settings

GitLab Basic Configurations

• Be sure to change TLS Certificate file name to the appropriate name /etc/gitlab/ssl/wildcard-${BASE_DOMAIN}.crt, /etc/gitlab/ssl/wildcard-${BASE_DOMAIN}.key

1. Ensure GITLAB_DOMAIN is defined as per the Shell Variables guide.

   export INSTANCE_TIME_ZONE="Asia/Bangkok"
   export TLS_CERTIFICATE_CERT_FILE="/etc/gitlab/ssl/wildcard-${BASE_DOMAIN}.crt"
   export TLS_CERTIFICATE_KEY_FILE="/etc/gitlab/ssl/wildcard-${BASE_DOMAIN}.key"

2. Create gitlab.rb File

   cat <<EOF >> /etc/gitlab/gitlab.rb
   # The URL through which GitLab will be accessed ; STRICT REQUIREMENT
   external_url "https://${GITLAB_DOMAIN}/"
   
   # Configure Timezone
   gitlab_rails['time_zone'] = "${INSTANCE_TIME_ZONE}"
   
   # Enable HTTP to HTTPS Redirection
   nginx['redirect_http_to_https'] = true
   # Enable TLS Certificate to GitLab Instance
   nginx['ssl_certificate'] = "${TLS_CERTIFICATE_CERT_FILE}"
   nginx['ssl_certificate_key'] = "${TLS_CERTIFICATE_KEY_FILE}"
   
   # Using your own TLS Certificate - Disable Free/Temporary TLS Certificate Request Module
   letsencrypt['enable'] = false
   
   # OPSTELLA_CUSTOMIZE: Enable Prometheus Metrics Exporter
   # Available on http://localhost:9168/metrics , http://GITLAB-INSTANCE-IP:9168
   prometheus['enable'] = true
   
   EOF

Opstella Integration: Clear Session Services Redirection

Note

You are about to configure a NGINX redirection that it must validate the endpoint of redirection.

If Opstella Clear-Session service not yet accessible, this WOULD cause GitLab NGINX Service to be down once you apply this.

You may configured with comments here and once you have Opstella Clear-Session setup and accessible, then you can come back and remove comments.

1. Set your information

   export OPSTELLA_CLEAR_SESSION_DOMAIN="clear-session.${BASE_DOMAIN}"

2. Create gitlab.rb File

   cat <<EOF >> /etc/gitlab/gitlab.rb
   # OPSTELLA_CUSTOMIZE: Enable Redirect to Opstella Clear Session Services Deployed on Kubernetes
   nginx['custom_gitlab_server_config'] = 'location /clear-session {
       proxy_pass https://${OPSTELLA_CLEAR_SESSION_DOMAIN};
       proxy_buffering off;
       proxy_set_header X-Real-IP \$remote_addr;
       proxy_set_header X-Forwarded-Host \$host;
       proxy_set_header X-Forwarded-Port \$server_port;
     }
   '
   
   EOF

Opstella Integration: Single Sign-On

• Create/Gather Opstella Keycloak OIDC Client ID, Client Secret. Create and gather from Procuring Keycloak Credentials

1. Set your information

   KEYCLOAK_DOMAIN and KEYCLOAK_REALM are assumed to be exported as defined in the Shell Variables guide.

   export GITLAB_CLIENT_ID="CHANGEME" 🔑
   export GITLAB_CLIENT_SECRET="CHANGEME" 🔑

2. Create gitlab.rb File

   cat <<EOF >> /etc/gitlab/gitlab.rb
   # OPSTELLA_CUSTOMIZE: Single Sign-On Integration
   gitlab_rails['omniauth_allow_single_sign_on'] = ['openid_connect']
   gitlab_rails['omniauth_block_auto_created_users'] = false
   
   gitlab_rails['omniauth_providers'] = [
     { 'name' => 'openid_connect',
       'label' => 'Opstella',
       'icon' => "/assets/auth_buttons/opstella-logo.svg",
       'args' => {
         'name' => 'openid_connect',
         'scope' => ['openid','profile','email'],
         'response_type' => 'code',
         'issuer' => 'https://${KEYCLOAK_DOMAIN}/realms/${KEYCLOAK_REALM}',
         'discovery' => true,
         'client_auth_method' => 'query',
         'uid_field' => 'preferred_username',
         'send_scope_to_token_endpoint' => 'false',
         'client_options' => {
         'identifier' => '${GITLAB_CLIENT_ID}', # Client ID
         'secret' => '${GITLAB_CLIENT_SECRET}', # Client Secret
           'redirect_uri' => 'https://${GITLAB_DOMAIN}/users/auth/openid_connect/callback'
         }
       }
     }
   ]
   
   EOF

Optional Configurations

Two Optional Configuration are:

• Git Repositories Data Location on the GitLab host

  This will be use in a scenario where your GitLab host main disk may have limited disk space, and you have an external disk mounted to GitLab host and instead would like to store Git Repositories that will be created when using GitLab stored on the location of the GitLab host specifically on the external disk that you mounted.

  Some System Administrator may do this as to make it easier to manage disk that critical to users as this is users data.

  Version Notice

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

  ## For GitLab 17.7 or older
  # The directory where Git repositories will be stored.
  # Default to `/var/opt/gitlab/git-data`
  git_data_dirs({"default" => {"path" => "/git-data"} })

  ## For GitLab 17.8 or newer
  gitaly['configuration'] = {
    storage: [
      {
        name: 'default',
        path: '/git-data/repositories',
      },
    ],
  }

• Backup storage location on the GitLab Host

  This will be use in a scenario where your GitLab host main disk may have limited disk space, in the backup process may use a lot of disk space and resolve disk space problem by mount an external disk to be its storage location

  # The directory where Gitlab backups will be stored
  # Default to `/var/opt/gitlab/backups`
  gitlab_rails['backup_path'] = "/data/gitlab/backups"

Post Configuration

Apply Configuration

sudo mv gitlab.rb /etc/gitlab/gitlab.rb
sudo chown root:root /etc/gitlab/gitlab.rb
sudo chmod 644 /etc/gitlab/gitlab.rb
sudo gitlab-ctl reconfigure

GitLab Testing

1. It should say the following, which means it successfully configured.

   ... (deducted)
   gitlab Reconfigured!

   Check GitLab Services Status

   sudo gitlab-ctl status

   It should say the following.

   ... (deducted)
   run: alertmanager: (pid 1757) XXXs; run: log: (pid 1748) XXXs
   run: gitaly: (pid 1754) XXXs; run: log: (pid 1744) XXXs
   run: gitlab-exporter: (pid 1747) XXXs; run: log: (pid 1733) XXXs
   run: gitlab-kas: (pid 1751) XXXs; run: log: (pid 1734) XXXs
   run: gitlab-workhorse: (pid 1740) XXXs; run: log: (pid 1730) XXXs
   run: logrotate: (pid 633591) 2147s; run: log: (pid 1758) XXXs
   run: nginx: (pid 1743) XXXs; run: log: (pid 1731) XXXs
   run: node-exporter: (pid 1739) XXXs; run: log: (pid 1729) XXXs
   run: postgres-exporter: (pid 1756) XXXs; run: log: (pid 1750) XXXs
   run: postgresql: (pid 1752) XXXs; run: log: (pid 1741) XXXs
   run: prometheus: (pid 1755) XXXs; run: log: (pid 1745) XXXs
   run: puma: (pid 1735) XXXs; run: log: (pid 1727) XXXs
   run: redis: (pid 1753) XXXs; run: log: (pid 1746) XXXs
   run: redis-exporter: (pid 1742) XXXs; run: log: (pid 1732) XXXs
   run: sidekiq: (pid 1737) XXXs; run: log: (pid 1728) XXXs

2. Visit gitlab.\${BASE_DOMAIN}, it should ready for you to login.