title: GitLab Pages
---
summary: Deploys to GitLab Pages.
---
body:

[GitLab](https://gitlab.com/) supports Lektor on their [GitLab
Pages](https://docs.gitlab.com/ee/user/project/pages/) infrastructure.  Effectively
GitLab can build your website out of any repository on GitLab and hosts it
up on either a subdomain or a custom domain (including SSL).

Because this is all supported by the side of GitLab there is nothing you
need to configure in Lektor itself other than adding a GitLab config file.

There is also an example project on GitLab with a README you can clone:
[pages/lektor](https://gitlab.com/pages/lektor)

## Create a Repository

What you need to do to start is to create a new repository for the project
on gitlab.  There are two types of GitLab pages: user and project pages.
User pages are hosted at `<username>.gitlab.io` and project pages at
`<username>.gitlab.io/<project>`.  There can only be one user page and the
repository for it needs to be named `<username>.gitlab.io`.

The branch does not matter.  GitLab scans all branches for a file named
`.gitlab-ci.yml` which contains a configuration for gitlab pages.

## Configuration

To enable support for Lektor you need to create a `.gitlab-ci.yml` config
next to your `.lektorproject` file with the following contents:

```yaml
image: python:latest

pages:
  script:
    - pip install lektor
    - lektor build --output-path public
  artifacts:
    paths:
      - public
  only:
    - master
```

It's important that the output path is set to `public` as this is what
will be served up.  In case you want to use a different branch than `master`
just name the branch differently and adjust the `only` entry.

Whenever you commit to the repository now, GitLab will automatically start
a job on the public infrastructure and deploy your website.

## Cache directory

You can enable caching to reuse build results between compilation.
To do so, you have to:

- set the cache directory using the environment variable `XDG_CACHE_HOME`;
- configure Gitlab to cache this directory.

See the example below.

```yaml
image: python:latest

default:
  cache:
    paths:
      - .cache/lektor
      - .cache/pip

variables:
  XDG_CACHE_HOME: "$CI_PROJECT_DIR/.cache"

pages:
  script:
    - pip install lektor
    - lektor build --output-path public
  artifacts:
    paths:
      - public
  only:
    - master
```

## CNAME Support

If you want to use a [CNAME :ext](https://en.wikipedia.org/wiki/CNAME) with
GitLab pages you can configure it in the GitLab settings:

* [Configure CNAME](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/#set-up-pages-with-a-custom-domain)

## SSL/TLS Support

If you have an SSL certificate and a custom domain, you can upload your private
key and certificate to GitLab and SSL will become available on your custom
domain as well.

* [Configure SSL/TLS](https://docs.gitlab.com/ee/user/project/pages/custom_domains_ssl_tls_certification/#adding-an-ssltls-certificate-to-pages)

## 404 Pages

Per convention the file named `404.html` is used as placeholder if a page
cannot be found.  You can create such a page by creating a `404.html/contents.lr`
file.