\section{Pourquoi du CI/CD pour LaTeX}
Traitez les documents comme du code
Les builds automatisés détectent les paquets défaillants et les erreurs de compilation avant qu'ils n'atteignent vos collaborateurs ou relecteurs. Un PDF n'est jamais qu'une exécution de pipeline plus loin.
Détectez les erreurs avant la fusion
Les vérifications du pipeline échouent si le document ne compile pas. Les relecteurs voient le LaTeX cassé avant qu'il n'arrive sur main.
Des artefacts à chaque exécution
GitLab conserve les PDF compilés comme artefacts de job. Téléchargez le dernier build directement depuis l'interface du pipeline.
Pas de TeX Live local nécessaire
Les contributeurs modifient les fichiers .tex sans installer une distribution TeX Live de 4 Go. La compilation s'effectue dans le cloud.
\section{Prerequisites}
Avant de commencer
- Un compte FormaTeX : l'offre gratuite suffit (15 compilations/mois)
- Une clé API FormaTeX depuis votre tableau de bord
- Un dépôt GitLab contenant des fichiers .tex
Définir la variable CI/CD
Dans GitLab, allez dans Settings › CI/CD › Variables › Add variable . Définissez la clé FORMATEX_API_KEY, collez votre clé API comme valeur et activez Masked pour qu'elle n'apparaisse jamais dans les journaux des jobs.
\section{Pipeline de base}
Votre premier .gitlab-ci.yml
Placez ce fichier à la racine de votre dépôt. Il récupère alpine:latest, installe curl et jq, compile main.tex et conserve le PDF obtenu comme artefact GitLab pendant une semaine.
# .gitlab-ci.yml
stages:
- build
compile-latex:
stage: build
image: alpine:latest
before_script:
- apk add --no-cache curl jq
script:
- |
curl -X POST https://api.formatex.io/api/v1/compile \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"latex\": $(cat main.tex | jq -Rs .), \"engine\": \"pdflatex\"}" \
--output output.pdf
artifacts:
paths:
- output.pdf
expire_in: 1 week
only:
- main
- merge_requests\section{Pipeline avancé}
Ancres YAML et jobs en parallèle
Passez à l'échelle sur plusieurs documents sans vous répéter. Ce pipeline utilise une ancre YAML pour définir un modèle de compilation réutilisable, puis l'instancie en parallèle pour main.tex et presentation.tex. Le job pages publie ensuite tous les PDF sur GitLab Pages.
# .gitlab-ci.yml — advanced with matrix and error handling
stages:
- validate
- build
- publish
variables:
FORMATEX_API_URL: "https://api.formatex.io/api/v1"
.compile-template: &compile
image: alpine:latest
before_script:
- apk add --no-cache curl jq
script:
- |
RESPONSE=$(curl -s -w "\n%{http_code}" \
-X POST "$FORMATEX_API_URL/compile" \
-H "X-API-Key: $FORMATEX_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"latex\": $(cat $TEX_FILE | jq -Rs .), \"engine\": \"$ENGINE\"}")
HTTP_CODE=$(echo "$RESPONSE" | tail -n1)
if [ "$HTTP_CODE" != "200" ]; then
echo "Error: $(echo "$RESPONSE" | head -n-1)"
exit 1
fi
echo "$RESPONSE" | head -n-1 > "$OUTPUT_FILE"
artifacts:
paths:
- "*.pdf"
expire_in: 30 days
compile-main:
<<: *compile
stage: build
variables:
TEX_FILE: main.tex
ENGINE: pdflatex
OUTPUT_FILE: main.pdf
compile-presentation:
<<: *compile
stage: build
variables:
TEX_FILE: presentation.tex
ENGINE: xelatex
OUTPUT_FILE: presentation.pdf
pages:
stage: publish
script:
- mkdir -p public
- cp *.pdf public/
artifacts:
paths:
- public
only:
- main\section{GitLab Pages}
Publier des PDF via GitLab Pages
Le job pages du pipeline avancé copie tous les PDF compilés dans le répertoire public/ et les expose sous forme de site GitLab Pages. Les documents compilés sont alors disponibles automatiquement à l'adresse https://<group>.gitlab.io/<project>/ à chaque push sur main. Aucun téléversement manuel, aucune configuration d'hébergement.
\section{Troubleshooting}
Problèmes courants et solutions
curl: command not found
Les images Alpine sont livrées sans curl par défaut. Incluez toujours apk add --no-cache curl jq dans votre before_script. Si vous passez à une image basée sur Debian, utilisez plutôt apt-get install -y curl jq.
Clé API non masquée dans les journaux
Assurez-vous d'avoir créé la variable avec l'option Masked activée dans GitLab Settings › CI/CD › Variables. Sans masquage, la clé apparaît en clair dans les journaux des jobs. Recréez la variable avec Masked activé.
Fichiers .tex volumineux qui dépassent le délai d'expiration
The sync endpoint has a timeout for very large documents. For files over 10 MB, switch to the async endpoint (/api/v1/compile/async) which returns a job ID. Poll /api/v1/jobs/{id} until the status is completed, then download the PDF from /api/v1/jobs/{id}/pdf.
\section{Intégrations associées}
Utilisez FormaTeX depuis n'importe quel environnement
FormaTeX est une simple API HTTP. Des exemples à copier-coller pour toutes les grandes plateformes.