Gitlab Pages

Index de la page

Mon premier site avec Gitlab Pages

Gitlab propose la fonctionnalité de Pages ! Il s'agit d'une fonctionnalité permettant d'exposer directement votre site internet au travers de la forge Gitlab. Le code de votre site et son exposition sont couplés, il vous suffit de push vos commits pour qu'un processus de mise à jour s'enclenche !

Pour ce tutoriel nous allons utiliser la page web suivante :

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width">
    <title>Mon premier site</title>
  </head>
  <body>
    <p>
      Nullam consequat varius eros, vitae volutpat arcu consequat quis. Praesent ac magna
      quis nisl mattis pulvinar sit amet vitae ipsum. Integer nec pretium erat,
      vitae tempus est. Phasellus id viverra mauris. Sed accumsan ac sapien at accumsan.
      Suspendisse ut enim eget urna vulputate ultrices. Vivamus id scelerisque leo.
      Sed mi purus, consectetur non dapibus a, tincidunt a massa.
      Etiam blandit egestas lectus, vitae lobortis leo consequat et.
      Aenean volutpat lectus vel magna imperdiet tincidunt.
    </p>
  </body>
</html>

Maintenant que nous avons un embryon de site, nous allons le publier avec Gitlab Pages ! Il vous suffit d'ajouter le fichier .gitlab-ci.yml suivant :

pages:
  stage: deploy
  script:
    - mkdir .public
    - cp -r * .public
    - mv .public public
  artifacts:
    paths:
      - public/

Qu'est-ce que ce code fait? C'est simple, il va créer un dossier caché du nom de .public, ensuite il va copier l'intégralité des fichiers du projet (à l'exception des fichiers et dossiers cachés !) dans le dossier caché .public. Dés que la copie est terminée, il va retirer l'aspect caché du dossier afin de pouvoir l'utiliser pour produire un artéfact qui sera la source de votre site web ! Le nom du job doit être pages.

Il est bien évidemment possible de coder directement son site web dans le dossier public. Si votre site devient important et que vous ne soutaiez pas tout exposer, il faudra faire attention au script du fichier .gitlab-ci.yml. Actuellement il copie l'intégralité du contenu dans le dossier public, tous les fichiers seront exposés sur internet !

Si le pipeline se termine correctement vous pouvez maintenant afficher votre site internet !

Le format de l'URI est toujours identique http://$CI_PROJECT_NAMESPACE/pages.univ-lyon1.fr/$CI_PROJECT_NAME/, ci-dessous les valeurs possible de CI_PROJECT_NAMESPACE:

Vous êtes personnel: prénom.nom
Vous êtes étudiant: p1234567
Le projet est membre d'un groupe: le nom du groupe

Par exemple pour ce projet de démonstration le lien est : http://doc-cicd.pages.univ-lyon1.fr/pages

Il est possible d'obtenir le lien avec l'interface web Gitlab en suivant les instructions suivantes. Une fois dans votre projet, vous allez dans Deploy(1), puis Pages(2). Vous trouverez directement le lien de votre site web (3) !

click-deploy-then-pages — Obtenir le lien de son site pages

Mon site avec du CSS et des images

Cet exemple fonctionne aussi avec des sites qui possèdent d'autres répertoires, des images, des fichiers CSS, etc. Nous allons créer une nouvelle page full.html avec un fichier CSS et une image. L'arborescence finale de notre projet sera la suivante :

tree-2levels-directories — Arborescence du projet

Le résultat en HTML de ce tutoriel est consultable ici. Vous pouvez aussi consulter les sources de ce projet sur la forge !

Contrôler les accès au dépôt et au site

Une force de Gitlab Pages est le contrôle qu'il offre aux développeurs. Comme dans l'exemple ci-dessus, il est possible de tout mettre en public. Mais il est aussi possible de restreindre les accès. Par défaut, Gitlab Pages va copier le niveau d'accès du dépôt ! Vous pouvez visiter le site web http://doc-cicd.pages.univ-lyon1.fr/private-pages/ puis constater que le dépôt https://forge.univ-lyon1.fr/doc-cicd/private-pages est inaccessible !

Si votre dépôt est privé et que vous souhaitez diffuser des informations au public, vous devez modifier le paramètre de visibilité, en vous rendant dans votre projet, puis vous allez cliquer sur Settings(1),General(2), puis Expand(3) dans la partie "Visibility, project features, permissions".

click-settings-general-expand — Les actions pour changer la visibilité

Descendez jusqu'à ce que vous puissiez voir la section Pages, vous trouverez une liste déroulante avec les trois (le nombre diffère selon la visibilité du dépôt) options suivantes :

Everyone : n'importe qui peut voir votre site web
Everyone With Access : tous les utilisateurs authentifiés sur la forge, disponible uniquement si le dépôt est en internal.
Only Project Members : uniquement les membres du projet peuvent voir le site

Faites votre choix puis n'oubliez pas de sauvegarder, le bouton se trouve un peu plus bas. (Aucune capture montre cette étape)

check-everyone-with-access-under-pages — Les droits de visibilité

Je souhaite utiliser un Static Site Generator (SSG)

Il est bien évidemment possible d'utiliser un Static Site Generator (SSG) avec Gitlab Pages. Avant de vous lancer, il faut comprendre les différences entre un site statique et dynamique, un bon moyen est de lire cet article (en anglais). Il est aussi possible de continuer en lisant cet autre article (en anglais) sur les avantages des SSG.

Si vous souhaitez vraiment vous lancer, la prochaine étape sera de choisir votre SSG. Ce choix sera crucial, il est conseillé de prendre un outil avec une communauté importante et une bonne documentation ! Ces deux critères vous permettront de trouver de l'aide sur internet en cas de pépin. De plus, vous pouvez prendre en compte le langage du SSG, vous serez plus à l'aise avec les erreurs, si le SSG est codé avec un langage que vous connaissez. Cet argument est d'autant plus important, si vous pensez que votre site nécessite des éléments complexes qui pourraient nécessiter le développement d'un plugin ! Si la documentation est bonne, la migration de votre fichier .gitlab-ci.yml vers un SSG devrait se passer très simplement, l'image Docker sera spécifiée ainsi que les étapes supplémentaires au script (installation des paquets, le build, etc.).

Gitlab a publié un un troisième article (en anglais). Vous pourrez y trouver plusieurs SSGs pour des environnements en Ruby, Python, Go et NodeJS. De nombreux SSGs sont documentés sur le dépôt pages de gitlab en indiquant une page par défaut du SSG et une version du fichier .gitlab-ci.yml. Ci-dessous une extraction du SSG le "mieux noté" sur la documentation officielle par environnement :

Environnement	Nom du SSG	Démonstration du thème	Dépôt témoin	fichier .gitab-ci.yml
Go	Hugo	démo	témoin	.gitlab-ci.yml
Ruby	Jekyll	démo	témoin	.gitlab-ci.yml
NodeJS	Hexo	démo	témoin	.gitlab-ci.yml
Python	Pelican	démo	témoin	.gitlab-ci.yml

Pourquoi je ne peux pas utiliser du HTTPS?

Vous avez peut être fait attention à ce détail dans les tutoriels, les URIs vers les sites sont en HTTP. En effet, dans notre établissement les logins des personnels contiennent un point. Ce point empêche d'utiliser un un certificat wildcard car il n'est possible de n'avoir qu'un seul wildcard dans le nom conformément à la RFC 6125.

Dans un autre établissement, vous avez peut être pu utiliser les domaines personnalisés afin de pouvoir changer l'URL d'accès à votre site. Pour transformer le prénom.nom en prénomnom ou le format de votre choix, cette solution technique est en cours d'étude.

Une solution alternative serait de proposer le HTTPS pour les groupes Gitlab, cela fonctionnerait pour les étudiants et les groupes avec aucun point dan le nom. Par contre, toutes les pages avec un projet de personnel retournerait une erreur HTTPS. Pour sensibiliser les utilisateurs à la sécurité, il n'est pas envisageable de proposer du HTTPS pour les groupes et de dire "vous acceptez ce certificat qui retourne une erreur" dans les autres situations, ça serait préjudiciable à la sensibilisation sur la sécurité informatique.