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. 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:

```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**: 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.

```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`**: 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:

```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** 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