Commit d00695a5 authored by Romain Lesur's avatar Romain Lesur
Browse files

explain the different jobs

parent c273a9f4
Pipeline #169080594 passed with stage
in 5 minutes and 40 seconds
# Details {#details}
A comprehensive documentation of `GitLab Pages` can be found here: https://docs.gitlab.com/ee/user/project/pages.
A comprehensive documentation of GitLab Pages can be found here: https://docs.gitlab.com/ee/user/project/pages.
## `GitLab CI` configuration file {#CI-file-details}
## GitLab CI configuration file {#CI-file-details}
`GitLab CI` configuration file is a `YAML` file.
The configuration file begins with `image` declaration. It indicates to the `GitLab Runner` which [`Docker`](https://www.docker.com/) image it has to pull for executing the `CI` job.
The GitLab CI configuration file is a YAML file named `.gitlab-ci.yml`.
### Docker image
Here, the configuration file begins with an `image` declaration. It indicates to the GitLab Runner which [Docker](https://www.docker.com/) image must be used by the CI job.
```{r find-image-name, comment=NA, class.output='yaml', echo=FALSE}
image <-
......@@ -18,24 +21,30 @@ image <-
unlist()
```
In order to build a website with `bookdown`, you have to choose a [`Docker`](https://www.docker.com/) image with `bookdown` installed. In this example, the `r image[1] %>% paste0("[\u0060", ., "\u0060](https://hub.docker.com/r/", ., ")")` image is used: [`Rocker`](https://www.rocker-project.org/) is the [official `R` image for `Docker`](http://dirk.eddelbuettel.com/blog/2014/12/19/). I am a newbie with [`Docker`](https://www.docker.com/) and I recommend this [rOpenSci](https://ropensci.org/)'s [Docker tutorial for reproducible research](http://ropenscilabs.github.io/r-docker-tutorial/).
In order to build a website with `bookdown`, you have to choose a [Docker](https://www.docker.com/) image with **bookdown** installed. In this example, the `r image[1] %>% paste0("[\u0060", ., "\u0060](https://hub.docker.com/r/", ., ")")` image is used: the [Rocker project](https://www.rocker-project.org/) provides the [official R image for Docker](http://dirk.eddelbuettel.com/blog/2014/12/19/). If you are new with [Docker](https://www.docker.com/), I highly recommend this [rOpenSci](https://ropensci.org/)'s [Docker tutorial for reproducible research](http://ropenscilabs.github.io/r-docker-tutorial/).
Using a Rocker image, **you can ensure the reproducibility of your bookdown website**.
Using a `Rocker` image, **you ensure the reproducibility of your `bookdown` website**.
### Jobs definition
In order to build a `GitLab Pages` website, you have to declare a `pages` job. That is the remaining lines of the `.gitlab-ci.yml` file:
The jobs are defined by the remaining lines of the `.gitlab-ci.yml` file:
```{r extract-pages-job, comment=NA, class.output='yaml', echo=FALSE}
readChar("./.gitlab-ci.yml", 1e5) %>%
strsplit("(?=\\npages:)", perl = TRUE) %>%
strsplit("(?=\\n\\.bookdown:)", perl = TRUE) %>%
unlist() %>%
stringr::str_subset("pages") %>%
stringr::str_subset("\\.bookdown") %>%
cat()
```
In this example, there is only a `deploy` stage, but you can add a `test` stage on any branch.
Here, we define 3 jobs:
- a hidden job named `.bookdown` (the trailing dot is used to declare a hidden job). This hidden job acts as a template for the two other jobs. This job declares the script used to build your **bookdown** book and indicates that the output files are located in the `public` folder (these are the artefacts).
- a `pages` job. This job is required to serve your **bookdown** book with GitLab Pages. It is highly recommended to run this job only when the `master` branch is modified.
## LaTeX engine
- a `mr-review` job. This job will allow you to preview the result of a pull request (with GitLab, pull requests are named merge requests). This job declares a different environment for each pull request. You can access to the preview site in the merge request page.
At the time this demo guide is written, there is only one pitfall: the `rocker/verse` image does not include `xelatex` `pdf` engine.
So, you have to use `pdflatex` instead of `xelatex`.
### Add a review application
The hidden gem in GitLab CI is the review application.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment