diff --git a/posts/ci-gitlab-latex.qmd b/posts/ci-gitlab-latex.qmd index f99493f..9844701 100644 --- a/posts/ci-gitlab-latex.qmd +++ b/posts/ci-gitlab-latex.qmd @@ -6,6 +6,8 @@ engine: knitr categories: [ci, intégration continue, git, GitLab, LaTeX, french, français] --- +:::{.content-visible when-profile="french"} + # La CI finale ```{bash, echo=FALSE} @@ -107,4 +109,112 @@ Maintenant vous pouvez faire référence dans votre `README.md` à vos PDF en sa `https://mongitlab.com/monnomutilisateur/mondepot/-/raw/monpdf.pdf` -qui permet d'afficher directement dans le navigateur le produit de la compilation. 😄 \ No newline at end of file +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. + +![In the left menus, expand "Settings" and go to "Access tokens"](resources/ci-gitlab-latex/access-token-settings.png) + +2. Here add a new token. + +![Click on "Add new token"](resources/ci-gitlab-latex/add-new-token.png) + +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". + +![](resources/ci-gitlab-latex/scope.png) + +4. Your token is now displayed, copy it as it will not be displayed again. + +5. Now go to CI/CD settings. + +![](resources/ci-gitlab-latex/ci-settings.png) + +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. 😄 +::: \ No newline at end of file