220 lines
No EOL
8.2 KiB
Text
220 lines
No EOL
8.2 KiB
Text
---
|
|
title: Faire une CI LaTeX avec GitLab
|
|
date: 23 09 2025
|
|
date-modified: last-modified
|
|
engine: knitr
|
|
categories: [ci, intégration continue, git, GitLab, LaTeX, french, français]
|
|
---
|
|
|
|
:::{.content-visible when-profile="french"}
|
|
|
|
# La CI finale
|
|
|
|
```{bash, echo=FALSE}
|
|
# This code is here to fetch the latest version of the CI from the Forge INRAE
|
|
curl -s "https://forge.inrae.fr/louis.lacoste/csi-louis/-/raw/main/.gitlab-ci.yml?ref_type=heads&inline=true" -o resources/ci-gitlab-latex/gitlab-ci.yaml
|
|
```
|
|
|
|
Voici le contenu d'un de mes fichier `.gitlab-ci.yaml`
|
|
|
|
::: {.callout-important}
|
|
Si vous voyez des incohérences, contactez-moi par mail : [louis.lacoste@agroparistech.fr](mailto:louis.lacoste@agroparistech.fr)
|
|
:::
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")
|
|
```
|
|
|
|
Détaillons ce qu'il s'y passe !
|
|
|
|
# Les variables
|
|
|
|
La section variables ci-dessous sert à définir des variables auxquelles nous ferons référence plus tard.
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")[1:9]
|
|
```
|
|
|
|
- `GIT_VERSION` : spécifie la version de git à utiliser pour l'image Docker que l'on va récupérer.
|
|
- `PDF_BRANCH` : indique le nom de la branche sur laquelle nos PDF seront publiés.
|
|
- `FILE_NAMES` : déclare la liste des noms de fichiers (sans les extensions). Au format yaml donc des chaînes de caractères sans guillemets séparés par des espaces
|
|
|
|
# Les étapes
|
|
## La phase de compilation `build_tex`
|
|
|
|
Nous allons détailler l'étape `build_tex` :
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")[10:36]
|
|
```
|
|
|
|
On déclare tout d'abord le `stage: build` pour qualifier l'étape que l'on réalise ici. Il y en a 3 possibles : `build, test, deploy` ([documentation GitLab](https://docs.gitlab.com/ci/yaml/#stage)).
|
|
Ici nous choisissons `build` puisqu'il s'agit de la compilation de notre projet.
|
|
|
|
À la suite nous chargeons une image docker qui contient les outils `texlive`.
|
|
|
|
Et enfin la directive `script` définit en `bash` l'enchaînement d'étapes que nous réalisons pour compiler le projet.
|
|
|
|
::: {.callout-note title="Exécution conditionnelle de `biber`"}
|
|
|
|
Noter que nous n'avons pas mis d'extensions dans `FILE_NAMES` afin de pouvoir détecter ici les fichiers bcf caractéristiques de la bibliographie.
|
|
|
|
:::
|
|
|
|
Finalement, nous utilisons la directive `after_script` pour afficher dans les journaux de la CI les fichiers de logs des compilations.
|
|
|
|
Enfin `artifacts` spécifie que les artéfacts que l'on veut conserver de la CI sont tous les PDF à la racine du dépôt
|
|
|
|
## La phase de déploiement `deploy`
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")[37:71]
|
|
```
|
|
|
|
Finalement nous déployons nos PDF. Pour cela on charge une image légère `Alpine Linux` avec la version Git sélectionnée dans les variables.
|
|
|
|
Avec la directive `before_script` on clone le dépôt.
|
|
|
|
::: {.callout-important title="Pour créer le token GitLab"}
|
|
Notez dans le `git clone` que nous employons une variable `GITLAB_TOKEN`, celle-ci est a créer au préalable et à déclarer dans le dépôt.
|
|
|
|
Pour cela :
|
|
|
|
1. Rendez-vous dans les paramètre de votre dépôt.
|
|
|
|
|
|
|
|
2. Ici ajoutez un nouveau token.
|
|
|
|
|
|
|
|
3. En configurant les permissions `read_repository` et `write_repository` afin de pouvoir cloner et pousser nos fichiers. Puis cliquer sur "Create project access token".
|
|
|
|
|
|
|
|
4. Votre token est maintenant affiché, copiez le car il ne sera pas raffiché après.
|
|
|
|
5. Rendez-vous maintenant dans CI/CD settings.
|
|
|
|
|
|
|
|
6. Créer maintenant la variable en cliquant sur "Add variable", nommez la `GITLAB_TOKEN`, dans "value" ajoutez le token copié.
|
|
|
|
:::
|
|
|
|
La suite du script déplace les PDF dans le dépôt cloné, crée la branche de publication et ajoute les pdf.
|
|
|
|
Vous avez normalement maintenant une CI de compilation et publication de PDF !
|
|
Maintenant vous pouvez faire référence dans votre `README.md` à vos PDF en saisissant un lien du type :
|
|
|
|
`https://mongitlab.com/monnomutilisateur/mondepot/-/raw/monpdf.pdf`
|
|
|
|
qui permet d'afficher directement dans le navigateur le produit de la compilation. 😄
|
|
:::
|
|
|
|
|
|
:::{.content-visible when-profile="english"}
|
|
|
|
# The Final CI
|
|
|
|
```{bash, echo=FALSE}
|
|
# This code is here to fetch the latest version of the CI from the Forge INRAE
|
|
curl -s "https://forge.inrae.fr/louis.lacoste/csi-louis/-/raw/main/.gitlab-ci.yml?ref_type=heads&inline=true" -o resources/ci-gitlab-latex/gitlab-ci.yaml
|
|
```
|
|
|
|
Here is the content of one of my `.gitlab-ci.yaml` files
|
|
|
|
::: {.callout-important}
|
|
If you see any inconsistencies, contact me by email: [louis.lacoste@agroparistech.fr](mailto:louis.lacoste@agroparistech.fr)
|
|
:::
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")
|
|
```
|
|
|
|
Let's break down what happens!
|
|
|
|
# Variables
|
|
|
|
The variables section below is used to define variables that we will reference later.
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")[1:9]
|
|
```
|
|
|
|
- `GIT_VERSION`: specifies the git version to use for the Docker image we're going to fetch.
|
|
- `PDF_BRANCH`: indicates the name of the branch on which our PDFs will be published.
|
|
- `FILE_NAMES`: declares the list of file names (without extensions). In yaml format, these are strings without quotes separated by spaces
|
|
|
|
# The Steps
|
|
## The compilation phase `build_tex`
|
|
|
|
Let's detail the `build_tex` step:
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")[10:36]
|
|
```
|
|
|
|
First, we declare `stage: build` to qualify the step we're performing here. There are 3 possible stages: `build, test, deploy` ([GitLab documentation](https://docs.gitlab.com/ci/yaml/#stage)).
|
|
Here we choose `build` since this is the compilation of our project.
|
|
|
|
Next, we load a docker image that contains the `texlive` tools.
|
|
|
|
Finally, the `script` directive defines in `bash` the sequence of steps we perform to compile the project.
|
|
|
|
::: {.callout-note title="Conditional execution of `biber`"}
|
|
|
|
Note that we haven't included extensions in `FILE_NAMES` so that we can detect here the bcf files characteristic of the bibliography.
|
|
|
|
:::
|
|
|
|
Finally, we use the `after_script` directive to display the compilation log files in the CI logs.
|
|
|
|
Lastly, `artifacts` specifies that the artifacts we want to keep from the CI are all PDFs at the root of the repository
|
|
|
|
## The deployment phase `deploy`
|
|
|
|
```{yaml}
|
|
#| code: !expr readLines("resources/ci-gitlab-latex/gitlab-ci.yaml", encoding = "UTF-8")[37:71]
|
|
```
|
|
|
|
Finally, we deploy our PDFs. For this, we load a lightweight `Alpine Linux` image with the Git version selected in the variables.
|
|
|
|
With the `before_script` directive, we clone the repository.
|
|
|
|
::: {.callout-important title="To create the GitLab token"}
|
|
Note in the `git clone` that we use a `GITLAB_TOKEN` variable, which must be created beforehand and declared in the repository.
|
|
|
|
To do this:
|
|
|
|
1. Go to your repository settings.
|
|
|
|
|
|
|
|
2. Here add a new token.
|
|
|
|
|
|
|
|
3. Configure the `read_repository` and `write_repository` permissions to be able to clone and push our files. Then click on "Create project access token".
|
|
|
|
|
|
|
|
4. Your token is now displayed, copy it as it will not be displayed again.
|
|
|
|
5. Now go to CI/CD settings.
|
|
|
|
|
|
|
|
6. Now create the variable by clicking on "Add variable", name it `GITLAB_TOKEN`, in "value" add the copied token.
|
|
|
|
:::
|
|
|
|
The rest of the script moves the PDFs to the cloned repository, creates the publication branch and adds the pdfs.
|
|
|
|
You should now have a CI for compiling and publishing PDFs!
|
|
Now you can reference your PDFs in your `README.md` by entering a link like:
|
|
|
|
`https://mygitlab.com/myusername/myrepo/-/raw/mypdf.pdf`
|
|
|
|
which allows you to display the compilation output directly in the browser. 😄
|
|
::: |