Skip to main content

GitLab Pages: Cloudflared

Below is a minimal example of how to configure a self-hosted GitLab instance to serve GitLab Pages behind Cloudflared. This guide walks through:

  1. Setting the GitLab Pages config on your self-hosted instance.  
  2. Creating a Cloudflared configuration to route traffic to GitLab Pages via a secure tunnel.

1. GitLab Configuration

In your GitLab configuration file (often /etc/gitlab/gitlab.rb for Omnibus installations), you might have something like:

external_url 'https://git.example.com'
pages_external_url 'https://pages.example.com'

# Disable usage reporting
gitlab_rails['usage_ping_enabled'] = false

# Pages configuration
gitlab_pages['enable'] = true
gitlab_pages['listen_proxy'] = "127.0.0.1:8090"
gitlab_pages['auth_servers'] = ["http://127.0.0.1:8090"]

# Domains served by GitLab Pages
gitlab_pages['domains'] = ["pages.example.com"]

# Enable the built-in Pages NGINX
pages_nginx['enable'] = true

# Listen for HTTPS in GitLab’s Pages component
nginx['listen_https'] = true
gitlab_pages['external_https'] = ['127.0.0.1:8443']

Note: The exact ports (e.g. 8090, 8443) may vary depending on your setup or preferences. Adjust as needed.

After editing, run:

sudo gitlab-ctl reconfigure

2. Example Cloudflared Configuration

Create or edit your Cloudflared configuration file, commonly found at:

/etc/cloudflared/config.yml

(Adjust the file path based on your system.)

Below is an example that:

  • Proxies pages.example.com to the GitLab Pages HTTPS listener on 127.0.0.1:8443.
  • Disables TLS verification (useful if your internal certificate is self-signed or otherwise untrusted).
  • Ensures the Host header remains pages.example.com so GitLab Pages recognizes the incoming request.
ingress:
  - hostname: pages.example.com
    service: https://127.0.0.1:8443
    originRequest:
      noTLSVerify: true
      httpHostHeader: pages.example.com

  # (Optional) If you want to proxy the main GitLab web UI:
  - hostname: git.example.com
    service: https://127.0.0.1:443
    originRequest:
      noTLSVerify: true
      httpHostHeader: git.example.com

  # Catch-all for any other requests
  - service: http_status:404

Important Keys

  1. hostname: Must match the domain you configured for GitLab Pages or the main GitLab instance.  
  2. service: Points to your local GitLab Pages HTTPS port (8443 in this example).  
  3. noTLSVerify: Bypasses TLS verification if your certificate is self-signed.  
  4. httpHostHeader: Ensures GitLab Pages sees the correct Host header, preventing unwanted redirects.

3. Restart Services

Apply your changes by restarting the necessary services:

sudo systemctl restart cloudflared

If you’re using Omnibus GitLab:

sudo gitlab-ctl reconfigure

4. Verify the Domain

In GitLab (under Settings → Pages for your project), ensure pages.example.com is added as the project’s custom domain. If it’s the only domain, consider marking it as “Primary” so that all traffic is served without redirects to other domains.

5. Test Your Setup

  1. Go to:          https://pages.example.com    
  2. Confirm your Pages site loads as expected (and is no longer redirecting to the main GitLab URL).

If you still see redirection or an error, double-check:

  • Cloudflare DNS: Ensure CNAME or A records for pages.example.com point to your Cloudflare Tunnel domain (often <tunnel-id>.cfargotunnel.com).  
  • GitLab Configuration: Confirm pages_external_url matches pages.example.com exactly and that the Pages domain is properly configured under Settings → Pages.  
  • Host Header: Make sure httpHostHeader is set in cloudflared to the Pages domain.

That’s it! With this configuration, requests to https://pages.example.com will be routed securely through Cloudflared to your self-hosted GitLab Pages service.

Back to top