Translated using DeepL

Machine-translated page for increased accessibility for English questioners.

Page in original, Czech language.

GitLab FI

GitLab Pages

GitLab Pages is a service that allows users to generate static pages directly from the repository. It is an ideal solution for

  • project or course web pages,
  • application documentation,
  • simple user pages.

Only static pages can be run in this service. It does not allow you to run server-side scripts or programs in any standard way. Therefore, it is not suitable for applications that require dynamic content generation, form processing, or asynchronous querying.

For these purposes, we recommend running the site on user pages on the Aisa server or in the Stratus.FI virtual environment.

How to do it

Getting a simple site up and running requires setting up a repository in GitLab and configuring CI to generate that site.

  • Select an appropriate namespace and project name

    The project name is deterministically mapped to the name of the page where the project appears. In general, a project in GitLab with a path
    https://gitlab.fi.muni.cz/namespace/[subns/…/]project.git
    will be available at the URL
    https://namespace.pages.fi.muni.cz/[subns/…/]project

    The namespace of user projects has namespace identical to the faculty login, and subns/…/ is empty because the user namespace has no subgroups. Therefore, for pages related to a course or research group project, we recommend using the group namespace rather than the faculty login.

    Pages in the domain root are a special case. If you as a user (or in a group) create a project with a name identical to the subdomain name, i.e. of the form
    https://gitlab.fi.muni.cz/namespace/namespace.pages.fi.muni.cz.git
    then the generated site will be placed in the root of the subdomain
    https://namespace.pages.fi.muni.cz/

    Tip: I want to request the creation of a group

  • Adjust visibility

    Faculty GitLab has an Access Control feature enabled for Pages that allows users to set access to web pages.

    Under Settings → General → Visibility, ... → Pages, you can select any of the following options to restrict access to these users, depending on the visibility of the project:

    Private Internal Public
    Only project members Project members project members project members
    Everyone with access cannot be selected users logged in GitLab FI anyone without a login
    Everyone anyone without login anyone without a login cannot be selected

  • Web content

    The structure of the site, the language used, etc. depends on the chosen generator, i.e. the program that creates the resulting static site. Most support Markdown or AsciiDoc, but you can also find specific generators, e.g. for generating documentation from source code. You can also write your own generator.

    Take inspiration from the examples

    Take a look at the official sample repositories. Most of them can be used as a skeleton for your own project.

    Beware of configuration files, in templates you often need to edit more than one configuration. If a template has README.md or similar help, read it carefully.

    Test the configuration
    We recommend starting with a very small number of pages first to see if the generator works at all.
    Custom generator
    You can also use a custom generator to generate content. Generation is done like any other task for GitLab CI. See the official documentation for the task setup requirements and where to expect the result.

  • CI/CD settings

    You can use a faculty instance of GitLab Runner or a custom instance to generate the site.

    To use a faculty instance, remember

    • set the shared-fitag in .gitlab-ci.yml for tasks,
    • verify that the container image for your chosen generator is available for the faculty GitLab CI, e.g. in the faculty administration application.

Additional information

The site will be automatically accessible via the https protocol with a certificate signed by Let's Encrypt.

The URL of the site can only be changed by moving the project. The path cannot be modified otherwise, even administratively.

Web content from your own domain

For research groups or major projects, we can set up a proxy from a domain of the form X.fi.muni.cz to provide content from GitLab Pages. Similarly, we can arrange to provide content from our own registered domain. Just have the registrar set up one of these options for the domain:

  1. domain IN CNAME gitlab.fi.muni.cz.
  2. domain IN A 147.251.58.80
          AAAA 2001:718:801:23a::50

Note that CVT does not provide domain registration outside of FI.

For exact terms and conditions, first contact the administrator at gitlab@fi.muni.cz.

Sample instance

Repository
The source repository in GitLab FI, which is a slightly modified template for Jekyll from the official source.
Result
A generated sample from the same repository.

If you don't know what to do with your own site:

Check the settings for GitLab CI
Project → Settings → CI/CD.
Check out .gitlab-ci.yml in the sample solution
This file contains task definitions for generating a site in a faculty environment.
Check the output of the failed task
GitLab project home page → CI/CD.

Useful links

Official GitLab user documentation

Faculty technical information