15 lines
No EOL
16 KiB
JSON
15 lines
No EOL
16 KiB
JSON
{
|
||
"hash": "19b99ce4fb75a2f71ce052a945b41f8b",
|
||
"result": {
|
||
"engine": "knitr",
|
||
"markdown": "---\ntitle: Faire une CI LaTeX avec GitLab\ndate: 23 09 2025\ndate-modified: last-modified\nengine: knitr\ncategories: [ci, intégration continue, git, GitLab, LaTeX, french, français]\n---\n\n\n\n\n\n:::{.content-visible when-profile=\"french\"}\n\n# La CI finale\n\n\n\n\n\n::: {.cell}\n\n:::\n\n\n\n\n\nVoici le contenu d'un de mes fichier `.gitlab-ci.yaml`\n\n::: {.callout-important}\nSi vous voyez des incohérences, contactez-moi par mail : [louis.lacoste@agroparistech.fr](mailto:louis.lacoste@agroparistech.fr)\n:::\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\nvariables:\n # Version de git utilisée\n GIT_VERSION: v2.30.1\n\n # Branche cible pour les PDF (modifiable via CI/CD variables)\n PDF_BRANCH: \"pdf\"\n\n FILE_NAMES: 2024-2025-rapport-csi 2024-2025-presentation-csi\n\nbuild_tex:\n stage: build\n image: danteev/texlive:latest # texlive plus inkscape and others\n script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"Compiling ${FILE_NAME}\"\n pdflatex --shell-escape ${FILE_NAME}.tex\n if test -f ${FILE_NAME}.bcf; then\n echo \"Found ${FILE_NAME}.bcf, running biber\"\n biber ${FILE_NAME}\n fi\n pdflatex --shell-escape ${FILE_NAME}.tex\n done\n after_script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"============================================\"\n cat ${FILE_NAME}.log\n echo \"============================================\"\n done\n\n artifacts:\n paths:\n - \"*.pdf\"\ndeploy:\n stage: deploy\n image:\n name: alpine/git:${GIT_VERSION}\n entrypoint: [\"\"]\n\n before_script:\n # Clone le repo dans un dossier temporaire\n - git clone \"https://${GITLAB_USERNAME}:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git\" \"${CI_COMMIT_SHA}\"\n\n # Configure l’identité git\n - git config --global user.email \"${GIT_USER_EMAIL:-$GITLAB_USER_EMAIL}\"\n - git config --global user.name \"${GIT_USER_NAME:-$GITLAB_USER_NAME}\"\n\n script:\n # Déplace les PDFs compilés dans le repo cloné\n - mv *.pdf \"${CI_COMMIT_SHA}/\"\n - cd \"${CI_COMMIT_SHA}\"\n\n # Crée une branche orpheline (vierge, sans historique ni fichiers)\n - git checkout --orphan \"${PDF_BRANCH}\"\n - git reset --hard\n\n # Ajoute uniquement les PDF\n - git add -f *.pdf\n\n # Vérifie s’il y a des changements et push\n - |\n CHANGES=$(git status --porcelain | wc -l)\n if [ \"$CHANGES\" -gt \"0\" ]; then\n git commit -m \"${COMMIT_MESSAGE:-Updating PDF files}\"\n git push --force origin \"${PDF_BRANCH}\" -o ci.skip\n else\n echo \"No PDF changes to commit\"\n fi\n```\n:::\n\n\n\n\n\nDétaillons ce qu'il s'y passe !\n\n# Les variables\n\nLa section variables ci-dessous sert à définir des variables auxquelles nous ferons référence plus tard.\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\nvariables:\n # Version de git utilisée\n GIT_VERSION: v2.30.1\n\n # Branche cible pour les PDF (modifiable via CI/CD variables)\n PDF_BRANCH: \"pdf\"\n\n FILE_NAMES: 2024-2025-rapport-csi 2024-2025-presentation-csi\n\n```\n:::\n\n\n\n\n\n- `GIT_VERSION` : spécifie la version de git à utiliser pour l'image Docker que l'on va récupérer.\n- `PDF_BRANCH` : indique le nom de la branche sur laquelle nos PDF seront publiés.\n- `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\n\n# Les étapes\n## La phase de compilation `build_tex`\n\nNous allons détailler l'étape `build_tex` :\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\nbuild_tex:\n stage: build\n image: danteev/texlive:latest # texlive plus inkscape and others\n script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"Compiling ${FILE_NAME}\"\n pdflatex --shell-escape ${FILE_NAME}.tex\n if test -f ${FILE_NAME}.bcf; then\n echo \"Found ${FILE_NAME}.bcf, running biber\"\n biber ${FILE_NAME}\n fi\n pdflatex --shell-escape ${FILE_NAME}.tex\n done\n after_script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"============================================\"\n cat ${FILE_NAME}.log\n echo \"============================================\"\n done\n\n artifacts:\n paths:\n - \"*.pdf\"\n```\n:::\n\n\n\n\n\nOn 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)).\nIci nous choisissons `build` puisqu'il s'agit de la compilation de notre projet.\n\nÀ la suite nous chargeons une image docker qui contient les outils `texlive`.\n\nEt enfin la directive `script` définit en `bash` l'enchaînement d'étapes que nous réalisons pour compiler le projet. \n\n::: {.callout-note title=\"Exécution conditionnelle de `biber`\"}\n\nNoter 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.\n\n:::\n\nFinalement, nous utilisons la directive `after_script` pour afficher dans les journaux de la CI les fichiers de logs des compilations.\n\nEnfin `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\n\n## La phase de déploiement `deploy`\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\ndeploy:\n stage: deploy\n image:\n name: alpine/git:${GIT_VERSION}\n entrypoint: [\"\"]\n\n before_script:\n # Clone le repo dans un dossier temporaire\n - git clone \"https://${GITLAB_USERNAME}:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git\" \"${CI_COMMIT_SHA}\"\n\n # Configure l’identité git\n - git config --global user.email \"${GIT_USER_EMAIL:-$GITLAB_USER_EMAIL}\"\n - git config --global user.name \"${GIT_USER_NAME:-$GITLAB_USER_NAME}\"\n\n script:\n # Déplace les PDFs compilés dans le repo cloné\n - mv *.pdf \"${CI_COMMIT_SHA}/\"\n - cd \"${CI_COMMIT_SHA}\"\n\n # Crée une branche orpheline (vierge, sans historique ni fichiers)\n - git checkout --orphan \"${PDF_BRANCH}\"\n - git reset --hard\n\n # Ajoute uniquement les PDF\n - git add -f *.pdf\n\n # Vérifie s’il y a des changements et push\n - |\n CHANGES=$(git status --porcelain | wc -l)\n if [ \"$CHANGES\" -gt \"0\" ]; then\n git commit -m \"${COMMIT_MESSAGE:-Updating PDF files}\"\n git push --force origin \"${PDF_BRANCH}\" -o ci.skip\n else\n echo \"No PDF changes to commit\"\n fi\n```\n:::\n\n\n\n\n\nFinalement 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.\n\nAvec la directive `before_script` on clone le dépôt.\n\n::: {.callout-important title=\"Pour créer le token GitLab\"}\nNotez 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.\n\nPour cela :\n\n1. Rendez-vous dans les paramètre de votre dépôt.\n\n\n\n2. Ici ajoutez un nouveau token.\n\n\n\n3. En configurant les permissions `read_repository` et `write_repository` afin de pouvoir cloner et pousser nos fichiers. Puis cliquer sur \"Create project access token\".\n\n\n\n4. Votre token est maintenant affiché, copiez le car il ne sera pas raffiché après.\n\n5. Rendez-vous maintenant dans CI/CD settings.\n\n\n\n6. Créer maintenant la variable en cliquant sur \"Add variable\", nommez la `GITLAB_TOKEN`, dans \"value\" ajoutez le token copié.\n\n:::\n\nLa suite du script déplace les PDF dans le dépôt cloné, crée la branche de publication et ajoute les pdf.\n\nVous avez normalement maintenant une CI de compilation et publication de PDF !\nMaintenant vous pouvez faire référence dans votre `README.md` à vos PDF en saisissant un lien du type : \n\n`https://mongitlab.com/monnomutilisateur/mondepot/-/raw/monpdf.pdf`\n\nqui permet d'afficher directement dans le navigateur le produit de la compilation. 😄\n:::\n\n\n:::{.content-visible when-profile=\"english\"}\n\n# The Final CI\n\n\n\n\n\n::: {.cell}\n\n:::\n\n\n\n\n\nHere is the content of one of my `.gitlab-ci.yaml` files\n\n::: {.callout-important}\nIf you see any inconsistencies, contact me by email: [louis.lacoste@agroparistech.fr](mailto:louis.lacoste@agroparistech.fr)\n:::\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\nvariables:\n # Version de git utilisée\n GIT_VERSION: v2.30.1\n\n # Branche cible pour les PDF (modifiable via CI/CD variables)\n PDF_BRANCH: \"pdf\"\n\n FILE_NAMES: 2024-2025-rapport-csi 2024-2025-presentation-csi\n\nbuild_tex:\n stage: build\n image: danteev/texlive:latest # texlive plus inkscape and others\n script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"Compiling ${FILE_NAME}\"\n pdflatex --shell-escape ${FILE_NAME}.tex\n if test -f ${FILE_NAME}.bcf; then\n echo \"Found ${FILE_NAME}.bcf, running biber\"\n biber ${FILE_NAME}\n fi\n pdflatex --shell-escape ${FILE_NAME}.tex\n done\n after_script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"============================================\"\n cat ${FILE_NAME}.log\n echo \"============================================\"\n done\n\n artifacts:\n paths:\n - \"*.pdf\"\ndeploy:\n stage: deploy\n image:\n name: alpine/git:${GIT_VERSION}\n entrypoint: [\"\"]\n\n before_script:\n # Clone le repo dans un dossier temporaire\n - git clone \"https://${GITLAB_USERNAME}:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git\" \"${CI_COMMIT_SHA}\"\n\n # Configure l’identité git\n - git config --global user.email \"${GIT_USER_EMAIL:-$GITLAB_USER_EMAIL}\"\n - git config --global user.name \"${GIT_USER_NAME:-$GITLAB_USER_NAME}\"\n\n script:\n # Déplace les PDFs compilés dans le repo cloné\n - mv *.pdf \"${CI_COMMIT_SHA}/\"\n - cd \"${CI_COMMIT_SHA}\"\n\n # Crée une branche orpheline (vierge, sans historique ni fichiers)\n - git checkout --orphan \"${PDF_BRANCH}\"\n - git reset --hard\n\n # Ajoute uniquement les PDF\n - git add -f *.pdf\n\n # Vérifie s’il y a des changements et push\n - |\n CHANGES=$(git status --porcelain | wc -l)\n if [ \"$CHANGES\" -gt \"0\" ]; then\n git commit -m \"${COMMIT_MESSAGE:-Updating PDF files}\"\n git push --force origin \"${PDF_BRANCH}\" -o ci.skip\n else\n echo \"No PDF changes to commit\"\n fi\n```\n:::\n\n\n\n\n\nLet's break down what happens!\n\n# Variables\n\nThe variables section below is used to define variables that we will reference later.\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\nvariables:\n # Version de git utilisée\n GIT_VERSION: v2.30.1\n\n # Branche cible pour les PDF (modifiable via CI/CD variables)\n PDF_BRANCH: \"pdf\"\n\n FILE_NAMES: 2024-2025-rapport-csi 2024-2025-presentation-csi\n\n```\n:::\n\n\n\n\n\n- `GIT_VERSION`: specifies the git version to use for the Docker image we're going to fetch.\n- `PDF_BRANCH`: indicates the name of the branch on which our PDFs will be published.\n- `FILE_NAMES`: declares the list of file names (without extensions). In yaml format, these are strings without quotes separated by spaces\n\n# The Steps\n## The compilation phase `build_tex`\n\nLet's detail the `build_tex` step:\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\nbuild_tex:\n stage: build\n image: danteev/texlive:latest # texlive plus inkscape and others\n script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"Compiling ${FILE_NAME}\"\n pdflatex --shell-escape ${FILE_NAME}.tex\n if test -f ${FILE_NAME}.bcf; then\n echo \"Found ${FILE_NAME}.bcf, running biber\"\n biber ${FILE_NAME}\n fi\n pdflatex --shell-escape ${FILE_NAME}.tex\n done\n after_script:\n - |\n for FILE_NAME in $FILE_NAMES\n do\n echo \"============================================\"\n cat ${FILE_NAME}.log\n echo \"============================================\"\n done\n\n artifacts:\n paths:\n - \"*.pdf\"\n```\n:::\n\n\n\n\n\nFirst, 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)).\nHere we choose `build` since this is the compilation of our project.\n\nNext, we load a docker image that contains the `texlive` tools.\n\nFinally, the `script` directive defines in `bash` the sequence of steps we perform to compile the project.\n\n::: {.callout-note title=\"Conditional execution of `biber`\"}\n\nNote that we haven't included extensions in `FILE_NAMES` so that we can detect here the bcf files characteristic of the bibliography.\n\n:::\n\nFinally, we use the `after_script` directive to display the compilation log files in the CI logs.\n\nLastly, `artifacts` specifies that the artifacts we want to keep from the CI are all PDFs at the root of the repository\n\n## The deployment phase `deploy`\n\n\n\n\n\n::: {.cell}\n\n```{.yaml .cell-code}\ndeploy:\n stage: deploy\n image:\n name: alpine/git:${GIT_VERSION}\n entrypoint: [\"\"]\n\n before_script:\n # Clone le repo dans un dossier temporaire\n - git clone \"https://${GITLAB_USERNAME}:${GITLAB_TOKEN}@${CI_SERVER_HOST}/${CI_PROJECT_PATH}.git\" \"${CI_COMMIT_SHA}\"\n\n # Configure l’identité git\n - git config --global user.email \"${GIT_USER_EMAIL:-$GITLAB_USER_EMAIL}\"\n - git config --global user.name \"${GIT_USER_NAME:-$GITLAB_USER_NAME}\"\n\n script:\n # Déplace les PDFs compilés dans le repo cloné\n - mv *.pdf \"${CI_COMMIT_SHA}/\"\n - cd \"${CI_COMMIT_SHA}\"\n\n # Crée une branche orpheline (vierge, sans historique ni fichiers)\n - git checkout --orphan \"${PDF_BRANCH}\"\n - git reset --hard\n\n # Ajoute uniquement les PDF\n - git add -f *.pdf\n\n # Vérifie s’il y a des changements et push\n - |\n CHANGES=$(git status --porcelain | wc -l)\n if [ \"$CHANGES\" -gt \"0\" ]; then\n git commit -m \"${COMMIT_MESSAGE:-Updating PDF files}\"\n git push --force origin \"${PDF_BRANCH}\" -o ci.skip\n else\n echo \"No PDF changes to commit\"\n fi\n```\n:::\n\n\n\n\n\nFinally, we deploy our PDFs. For this, we load a lightweight `Alpine Linux` image with the Git version selected in the variables.\n\nWith the `before_script` directive, we clone the repository.\n\n::: {.callout-important title=\"To create the GitLab token\"}\nNote in the `git clone` that we use a `GITLAB_TOKEN` variable, which must be created beforehand and declared in the repository.\n\nTo do this:\n\n1. Go to your repository settings.\n\n\n\n2. Here add a new token.\n\n\n\n3. Configure the `read_repository` and `write_repository` permissions to be able to clone and push our files. Then click on \"Create project access token\".\n\n\n\n4. Your token is now displayed, copy it as it will not be displayed again.\n\n5. Now go to CI/CD settings.\n\n\n\n6. Now create the variable by clicking on \"Add variable\", name it `GITLAB_TOKEN`, in \"value\" add the copied token.\n\n:::\n\nThe rest of the script moves the PDFs to the cloned repository, creates the publication branch and adds the pdfs.\n\nYou should now have a CI for compiling and publishing PDFs!\nNow you can reference your PDFs in your `README.md` by entering a link like:\n\n`https://mygitlab.com/myusername/myrepo/-/raw/mypdf.pdf`\n\nwhich allows you to display the compilation output directly in the browser. 😄\n:::",
|
||
"supporting": [],
|
||
"filters": [
|
||
"rmarkdown/pagebreak.lua"
|
||
],
|
||
"includes": {},
|
||
"engineDependencies": {},
|
||
"preserve": {},
|
||
"postProcess": true
|
||
}
|
||
} |