Get the full power of GitLab CI for your bookdown project
2020-09-08
Overview: a powerful workflow
Publishing a bookdown (Xie 2020) website with GitLab Pages is as easy as:
- 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.
References
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↩︎