Gitlab Pages

Step-by-step guide on how to get started with Gitlab Pages.

1

Create a Gitlab Repository

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.usc.es/pagename, name your project as pagename inside the desired namespace.

If you want a URL in the form namespace.pages.citius.usc.es, name your project as namespace.pages.citius.usc.es, being namespace your current username or group name.

Initialize your repository as usual, with a README.md file.

2

Start writing your website

You can copy over your existing website, or start writing a new one from scratch, and commit it as usual.

$ git add index.html
$ git commit -m "First commit"
$ git push -u origin master

3

Create a Gitlab CI configuration file

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:
  - master

This is a simple Gitlab CI job definition that will copy the content of the master 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.

$ git add .gitlab-ci.yml
$ git commit -m "Added Gitlab CI job to deploy the website"
$ git push

4

Wait for Gitlab CI to do its magic

Deployment should start as soon as you push the Gitlab CI job definition to the repository.

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! 🎉

Yay!

But wait, don't stop listening! We are not done yet!

5

Wait for SSL Certificates!

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.

6

Dive into Gitlab CI

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.usc.es.

Bothered by too much e-mails? Go to your Notifications Settings and disable notifications for that specific project or group.

1

Create a gl-pages branch

The URL of your website will be namespace.pages.citius.usc.es/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.usc.es 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 .

2

Start writing your website

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

3

Create a Gitlab CI configuration file

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

4

Wait for Gitlab CI to do its magic

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! 🎉

Yay!

But wait, don't stop listening! We are not done yet!

5

Wait for SSL Certificates!

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.

6

Dive into Gitlab CI

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.