README.md 4.72 KB
Newer Older
Florent Chehab's avatar
Florent Chehab committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106
Intégration Continue : **LaTeX** et **GitLab**.
======= 

- [Démonstration](#d%C3%A9monstration)
- [Explications](#explications)
  - [Prérequis : activer le _shared Runner_](#pr%C3%A9requis-activer-le-shared-runner)
  - [C'est parti](#cest-parti)
    - [Remarques](#remarques)
  - [Commentaires sur l'intégration continue](#commentaires-sur-lint%C3%A9gration-continue)
    - [Pour aller plus loin](#pour-aller-plus-loin)

# Démonstration
Ce _repo_ est en lui-même un démonstation de l'utilisation de l'intégration continue pour la compilation de LaTeX. Le fichier `main.tex` est compilé (voir [Explications](#explications)) et le `pdf` est disponible [ici](https://gitlab.utc.fr/LaTeX-UTC/LaTeX-CI/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master).

N'hésitez pas à cloner ce _repo_ pour vous en servir comme base.


# Explications 

## Prérequis : activer le _shared Runner_

1. Rendez-vous das les `paramètres` du projet GitLab, section `CI/CD`.
1. Cliquez sur `Runners settings` (_expand_).
1. Dans la section _Shared Runners_, cliquez sur _« Activate shared Runners »_.


## C'est parti 

Vous n'avez plus qu'à modifier le fichier `main.tex` et à _commit_ les changements, la compilation et la publication à l'adresse `https://gitlab.utc.fr/<login-ou-namespace>/<nom-du-projet>/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master` se fait automatiquement. Par exemple, pour ce projet, le pdf est disponible à l'adresse [https://gitlab.utc.fr/LaTeX-UTC/LaTeX-CI/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master](https://gitlab.utc.fr/LaTeX-UTC/LaTeX-CI/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master).


### Remarques 

- Les `pdf` compilés sont rendus disponibles en public via les _artifacts_. Ces derniers peuvent être visualisés via :
  - La page d'accueil du projet, cliquez sur l'icône _télécharger_ puis sur `Télécharger 'building-latex-master'`
  - Dans le menu du projet, cliquez sur `CI/CD` -> `jobs`, puis sur le badge (espérons "réussi") du status associé au job souhaité, puis dans le menu de droite, dans la section `Job artifacts` cliquez sur `browse`.
  - Url : 
    -  Pour la branche master : `https://gitlab.utc.fr/<login-ou-namespace>/<nom-du-projet>/-/jobs/artifacts/master/raw/main.pdf?job=building-latex-master`
    -  Pour les autres branches : `https://gitlab.utc.fr/<login-ou-namespace>/<nom-du-projet>/-/jobs/artifacts/<nom-de-la-branche>/raw/main.pdf?job=building-latex-other-branch`
- Si la compilation échoue, le _job_ sera marqué comme tel et vous pouvez accéder aux logs pour savoir où elle a échouée. 
- _Pensez à adapter la license à votre projet._

## Commentaires sur l'intégration continue
Avec GitLab, toute l'intégration continue est gérée via le fichier `.gitlab-ci.yml`. Voici celui utilisé par ce projet (avec quelques commentaires).

Il comporte 2 _jobs_ sensiblement similaires qui permettent une gestion optimale des ressources disques : à l'heure de la réalisation de ce projet il n'est pas [encore](https://gitlab.com/gitlab-org/gitlab-ce/issues/23777) possible de garder uniquement les derniers artifacts. Pour contourner le système : 
- Les artifacts issus de la branche master sont conservés 2 ans.
- Les artifacts issus des autres branches sont conservés 2 semaines.

```yaml
# Téléchargement d'une image Docker avec tous les packets
# texlive pour éviter les ennuis lors de la compilation latex
image: blang/latex

# Premier job : compilation du latex
building-latex-master:
  stage: build
  script:
    # Compilation avec latexmk du fichier main.tex 
    # qui est à la racine du repo
    - latexmk -pdf main.tex
  artifacts:
    # Génération d'une archive téléchargeable avec le fichier
    paths:
      - "*.pdf"
    expire_in: 2 year # Durée de validité de l'archive
  tags:
    # Tag pour que le shared runner du GitLab de l'UTC 
    # fasse sont travail.
    - docker

# Deuxième job : similaire, mais pour les autres branches
building-latex-other-branch:
  stage: build
  script:
    - latexmk -pdf main.tex
  artifacts:
    paths:
      - "*.pdf"
    expire_in: 2 week # durée plus courte
  except: # toutes les branches sauf master
    - master
  tags:
    - docker
```


### Pour aller plus loin

Dans la partie `script` d'un job décrit dans le fichier `.gitlab-ci.yml` vous pouvez installer des packets (`apt-get install --yes <nom-du-paquet>`) voire exécuter des scripts bash qui seraient disponibles dans le repo :
```yaml
# [...]
building-latex-master:
  stage: build
  script:
    - bash build.sh
# [...]
```

Les possibilités sont donc infinies :)

- Un peu de lecture : https://gitlab.com/help/user/project/pipelines/job_artifacts.md
- Pour tester vos fichiers `.gitlab-ci.yml` : https://gitlab.utc.fr/ci/lint


**Amusez-vous bien.** :wink: