Get the full power of GitLab CI for your bookdown project
Overview: a powerful workflow
- hosting a repository on GitLab
- adding a configuration file to the project
You will get a hosting service for your bookdown book (like GitHub Pages) and great features which are not available with GitHub Actions and GitHub Pages:
- pull requests previews
- a review application dedicated to non git users that allows them to comment on these previews
Host a project on GitLab
As GitHub, GitLab is a web-based Git repository manager. Creating a new project on GitLab is fairly intuitive for GitHub users. GitLab users can create unlimitate private projects for free (see here).
GitLab also offers a continuous integration service (GitLab CI) and a static websites hosting service (GitLab Pages) in its free plan.1
These features are also present in the open source software GitLab Community Edition (CE) which is widely used in industry as a self hosted git repository manager.
Add a GitLab CI configuration file
Add the following
.gitlab-ci.yml file in the root of the project:
image: rocker/verse:4.0.2 .bookdown: stage: deploy script: - Rscript -e "bookdown::render_book('index.Rmd', 'all', output_dir = 'public')" artifacts: paths: - public pages: extends: .bookdown only: - master mr-review: extends: .bookdown after_script: - echo "ENVIRONMENT_URL=https://$CI_PROJECT_NAMESPACE.$CI_PAGES_DOMAIN/-/$CI_PROJECT_NAME/-/jobs/$CI_JOB_ID/artifacts/public/index.html" >> deploy.env artifacts: reports: dotenv: deploy.env environment: name: review/$CI_COMMIT_REF_NAME url: $ENVIRONMENT_URL only: - merge_requests
For explanations, see section 1.
See the result
When the CI job is done, the website is served on GitLab Pages.
CI jobs status can be found in
CI / CD menu > Jobs. An example, here.
The address of the
GitLab Pages project can be found in
Settings > Pages. An example, here.
For each merge request, you also can access to a preview version of your website. Here is a demo:
click on the button View app
note the Review button on the right hand side of the website. With this button, you can leave a feedback on the merge request.
Xie, Yihui. 2020. Bookdown: Authoring Books and Technical Documents with R Markdown. https://github.com/rstudio/bookdown.
CI pipelines are limited to 2,000 minutes per month↩︎