How GitLab Pages Uses the GitLab API to Serve Content

How GitLab Pages Generates Routes

Prior to GitLab 12.10, the Pages daemon relied on a configuration file named config.json within the project directory to generate routes for serving pages. This file would typically be located at:

/path/to/shared/pages/myproject/myproject.gitlab.io/config.json

However, starting from GitLab 12.10, the Pages daemon no longer depends on this config.json file. Instead, it sources its configuration from the GitLab API via an internal API endpoint:

/api/v4/internal/pages?host=myproject.gitlab.io

The response from this API call closely mirrors the structure of the old config.json file but is now dynamically fetched. Here’s an example of the API response:

{
    "certificate": "--cert-contents--",
    "key": "--key-contents--",
    "lookup_paths": [
        {
            "access_control": true,
            "https_only": true,
            "prefix": "/",
            "project_id": 123,
            "source": {
                "path": "myproject/myproject.gitlab.io/public/",
                "type": "file"
            }
        }
    ]
}

This configuration contains:

certificate: The SSL certificate contents for secure HTTPS communication.
key: The SSL private key.
lookup_paths: An array of paths that define how the Pages daemon should look up the content and serve it.

Each entry under lookup_paths defines:

access_control: A flag indicating if access control is enabled.
https_only: A flag indicating whether the content should only be served over HTTPS.
prefix: The base path for serving content.
project_id: The ID of the GitLab project that hosts the Pages.
source: Defines the source of the content, including the path to the project’s public files.

How GitLab Pages Serves Content

Once the configuration is fetched and the routes are generated, the Pages daemon starts serving the content. Here’s how the process works:

The gitlab-pages Command Option: The gitlab-pages command is started with the option pages-root, which specifies the directory where the Pages content is stored. For example:
```
gitlab-pages -pages-root="shared/pages"
```
Domain Source Configuration: The API response contains the source configuration, which specifies the root path for serving content. In our example, this path is:
```
"path": "myproject/myproject.gitlab.io/public/"
```
Resolving the Path: The Pages daemon uses the reader.resolvePath function to parse the requested URL.subpath from the incoming request. This function determines the exact location of the requested content.

You can check out the implementation of reader.resolvePath in the GitLab Pages source code.
Serving the Content: Finally, the resolved file path is constructed, and the Pages daemon serves the requested content. For example, the final path might be:
```
shared/pages/myproject/myproject.gitlab.io/public/URL.subpath
```
The content at this path is then served to the user.

How GitLab Pages Generates Routes

How GitLab Pages Serves Content

References