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, andsubns/…/
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/
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
orAsciiDoc
, 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, be sure to set the
shared-fi
tag in.gitlab-ci.yml
for tasks.
Read more
The site will be automatically accessible via
https
with a certificate signed by
Let's Encrypt.
The URL of the site can only be changed by moving the project. Otherwise the path cannot be modified, even administratively.
Web content from your own domain
Site content from
pages.fi.muni.cz
can also be served from other domains. There are several options to choose from.
Custom domain outside
fi.muni.cz
Prerequisites
- Secure your own domain. CVT does not provide registration.
- The domain registrar must be able to set up records like
A
,AAAA
andTXT
for verification. - Optionally, you can have your own certificate. By default, GitLab will request a Let's Encrypt authority certificate and maintain it itself.
Setting up
-
Open the GitLab Pages settings
In the project, in the left panel, find
Deploy →
Pages.
If you don't see this option, make sure this property is enabled in the project: Settings → General → Visibility, project features, permissions. -
Set up a new domain
- Click
New Domain.
- In the Domain field, type the domain name.
- If you have your own certificate, cancel
Automatic certificate management and insert your own certificate and key in PEM format.
If GitLab reports errors, try inserting an intermediate certificate as well. - Click Create New Domain.
- Click
New Domain.
-
Save the verification code
After creating the domain, GitLab will give you a code of the form
_gitlab-pages-verification-code.$DOMAIN TXT gitlab-pages-verification-code=$TOKEN
-
Set up the new domainThen ask the domain registrar to set up the following records (the third line is the code from the previous step):
$DOMAIN in A 147.251.58.89 in AAAA 2001:718:801:23a::59 _gitlab-pages-verification-code.$DOMAIN TXT gitlab-pages-verification-code=$TOKEN
- Verify the domain After confirming the settings from the registrar, click the renew button in the Verification Status section of GitLab. If GitLab successfully verifies the domain, it will generate a certificate for the domain and start serving it.
- Done You should now see the page content on the new domain.
Custom domain outside of
fi.muni.cz
(alternative)
If your domain registrar does not allow you to establish a
TXT
record, consider another registrar first.
Alternatively, you can establish a domain with a proxy. In this case, the registrar must be able to handle at least the
A
and
AAAA
records. The domain will use a
Let's Encrypt authority certificate managed by CVT. No other certificates can be used.
The exact settings for the registrar will be communicated to you by the administrators. Contact
gitlab2pchoJahy@fixEBCrY4_t.muniG_7b5My_L.cz
.
Pages in the domain
fi.muni.cz
CVT, as the registrar for the domain
fi.muni.cz
, can introduce records of the form
example.fi.muni.cz
, or also
example.lab.fi.muni.cz
.
First, make a domain reservation at
gitlabocVp7SzaG@fihFOG_WGvt.muniN9ILM9GGY.cz
. In the request, specify which project is involved and whether you want to use a custom certificate. If everything is in order, the administrators will set up the domain for the site.
If you are unsure or have questions, contact the administrators at
gitlabtBvmd3wPT@fiB1A6U9993.muniNXvt34gKJ.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 page:
- Check the settings for GitLab CI
- Project → Settings → CI/CD.
- Check out
.gitlab-ci.yml
In the sample solution - This file contains the 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