Skip to main content

Configuring GitLab Pages behind 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.

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

    3. ---

##

1. GitLab Configuration

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

```ruby

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**Note: The exact ports (e.g. `8090`8090, `8443`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`com to the GitLab Pages HTTPS listener on `127.0.0.1:8443`8443.
    -
  • Disables TLS verification (useful if your internal certificate is self-signed or otherwise untrusted).
    -
  • Ensures the Host header remains `pages.example.com`com so GitLab Pages recognizes the incoming request.

    • ```yaml

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

    5. ---

##

3. Restart Services

Apply your changes by restarting the necessary services:

```bash

sudo systemctl restart cloudflared
```

If you’re using Omnibus GitLab:

```bash

sudo gitlab-ctl reconfigure
```


---

##

4. Verify the Domain

In GitLab (under **Settings → Pages**Pages for your project), ensure `pages.example.com`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.

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

---

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

Back to top