GitLab Pages

Overview#

glci pages serve extracts the artifact from a Pages-enabled job and serves it over HTTP, so you can preview your GitLab Pages site locally after running a pipeline.

A Pages job is one that declares pages: true or pages: { publish: "dir" } in .gitlab-ci.yml. The publish directory (default public/) within the artifact is served. If the publish directory is not found, the artifact root is served.

Usage#

# Serve from the latest pipeline (auto-detects Pages job)
glci pages serve

# Serve from a specific pipeline
glci pages serve 5

# Serve a specific job by name (latest pipeline)
glci pages serve deploy-pages

# Serve a specific pipeline and job
glci pages serve 5 deploy-pages

# Custom port (default: 8080)
glci pages serve --port 3000

# Bind to all interfaces
glci pages serve --host 0.0.0.0

How it works#

1. Finds the latest pipeline (or the one you specify) that has a Pages-enabled job with artifacts.
2. Extracts the artifact zip into a temporary directory.
3. Locates the publish directory within the extracted artifact (public/ by default, or the value from pages: { publish: "dir" }).
4. Starts an HTTP file server on 127.0.0.1:8080 (configurable with --host and --port).
5. If the preferred port is taken, automatically tries the next 9 ports, then falls back to an OS-assigned port.

Press Ctrl+C to stop the server.

Flags#

Typical workflow#

# 1. Run your pipeline (includes a Pages job)
glci run

# 2. Preview the Pages site
glci pages serve
# Serving Pages from pipeline #1, job "pages" (42 files)
#   URL: http://127.0.0.1:8080
#   Press Ctrl+C to stop

Job detection#

glci pages serve auto-detects Pages jobs in this order:

1. Jobs with pages: true or pages: { publish: "..." } that have artifacts.
2. A job named pages (legacy convention) that has artifacts.

You can bypass auto-detection by specifying the job name explicitly.