Step-by-step guide on how to get started with Gitlab Pages.
Click on the button New Project on Gitlab. The name will define the URL of the website.
If you want a URL in the form namespace.pages.citius.gal/pagename
, name your project as pagename
inside the desired namespace
.
If you want a URL in the form namespace.pages.citius.gal
, name your project as namespace.pages.citius.gal
, being namespace
your current username or group name.
Choose "Create from template" and on Pages/Jekyll press the button "Use template". Alternatively, you could also use any other template starting with Pages.
Assuming you are using Pages/Jekyll, modify the file _config.yml
and setup the correct baseurl
.
If you are using any other template such as Pages/Hugo, please read the README.md
.
Deployment should start now!
You can follow the process from the project main site in Gitlab, with a Pending, Running, Passed or Failed badge. You can click on this badge if you need more information.
Once the process is in state Passed, your website should be available! 🎉
But wait, don't stop listening! We are not done yet!
New SSL certificates are issued automatically at least three times a week. If you are deploying in a new domain, you might encounter SSL errors meanwhile.
The process is automated and automated things sometimes go south, so please tell us if you find that your certificates are not issued properly after some days.
The deployment is done by a Docker Runner with an Ubuntu image, but you can specify alternative images. Refer to the documentation or ask us for assistance.
You can also deploy your own Gitlab Runner and setup your project to use it. Just go to CI/CD Pipelines submenu and follow the steps.
If you want to learn from examples, this very same website has been built following this method. Take a look at this website repository in Gitlab.
Please notice that you can also use the domain citiususc.io
as a shortener, so namespace.citiususc.io
should redirect you to namespace.pages.citius.gal
.
Bothered by too much e-mails? Go to your Notifications Settings and disable notifications for that specific project or group.
gl-pages
branchThe URL of your website will be namespace.pages.citius.gal/reponame
, being reponame
the name of your software in that namespace
(your user or some group).
If you want a website whose URL is namespace.pages.citius.gal
you will have to create a separate repository. Follow the New repository guide instead.
Assuming you want to do the first thing, create an empty branch named gl-pages
.
$ git checkout --orphan gl-pages $ git rm -rf .
You can copy over your existing website, or start writing a new one from scratch.
Remember that you must push to the remote gl-pages
branch, so you will need to specify it the first time.
$ git add index.html $ git commit -m "First commit" $ git push -u origin gl-pages
To change back and forth between your project and your project website, just checkout the corresponding branch.
$ git checkout master $ git checkout gl-pages
While in gl-pages
branch, create a new file named .gitlab-ci.yml
with the following content:
pages: stage: deploy script: - mkdir .public - cp -r * .public - mv .public public artifacts: paths: - public only: - gl-pages
This is a simple Gitlab CI job definition that will copy the content of the gl-pages
branch into a directory for deploy
.
You can use other names, change and/or add more commands with the neccessary bash commands to build your website.
Add the file to a commit and push it to the remote, always while in gl-pages
branch.
$ git add .gitlab-ci.yml $ git commit -m "Added Gitlab CI job to deploy the website" $ git push
Deployment should start as soon as you push the Gitlab CI job definition to the repository.
You can follow the process from the project site in Gitlab choosing the correct branch, with a Pending, Running, Passed or Failed badge. You can click on this badge if you need more information.
Once the process is in state Passed, your website should be available! 🎉
But wait, don't stop listening! We are not done yet!
New SSL certificates are issued automatically at least three times a week. If you are deploying in a new domain, you might encounter SSL errors meanwhile.
The process is automated and automated things sometimes go south, so please tell us if you find that your certificates are not issued properly after some days.
The deployment is done by a Docker Runner with an Ubuntu image, but you can specify alternative images. Refer to the documentation or ask us for assistance.
You can also deploy your own Gitlab Runner and setup your project to use it. Just go to CI/CD Pipelines submenu and follow the steps.
If you want to learn from examples, this example project has its own website built using this method.
Please notice that you can also use the domain citiususc.io
as a shortener, so namespace.citiususc.io
should redirect you to namespace.pages.citius.usc.es
.
Bothered by too much e-mails? Go to your Notifications Settings and disable notifications for that specific project or group.