R/Shiny Training: Should you find this blog to be of interest, kindly note that I offer personalized and group-based training sessions that may be reserved through Buy me a Coffee. Additionally, I provide training services in the Spanish language and am available to discuss means by which I may contribute to your Shiny project.
Here I explain how to use GitHub Actions to deploy a bookdown site to gh-pages. This approach is more simple than what I used for the R4DS in Spanish project, and also simpler than some of the approaches I have seen in other blogs.
GitHub Actions is a Continuous Integration (CI) tool that allows you to automate tasks such as building and deploying your bookdown site. In this post, I will explain how to use GitHub Actions to deploy a bookdown site to gh-pages.
For the R4DS in Spanish project we proceeded in the following order to facilitate contributions:
- Each user had to translate a chapter in RMarkdown format and submit a pull request.
- Once the pull request was approved, the chapter was merged into the main branch.
- GitHub Actions detected the merge and the site for Spanish version of the book was updated.
The problem with this approach is that, while it was simpler for contributors, Netlify had some recent changes. One of these changes was disabling the Ubuntu 16 image, which was used in the chain of steps to build the bookdown site. This left us unable to update the rendered site for R4DS in Spanish.
But we can also use GitHub Actions without Netlify. This is the approach that I implemented now. If you look at the configuration file for GitHub Actions in the R4DS in Spanish repository, you will see that it is very simple. It consists in the following steps:
- Configure a virtual machine.
- Build the bookdown site.
- Update the site for the project.
These steps should be ideal for teams where different people are working on the same project and changing different files at the same time, and this will avoid pushing many different local versions of the site to the repository while focusing on the contents.
For the first step, the gh-actions configuration installs R
and all the dependencies for the R4DS in Spanish project site. The simplest option we found was to create a
DESCRIPTION file with all the dependencies,
as one would do with an R package (https://github.com/cienciadedatos/r4ds/blob/traduccion/DESCRIPTION).
For the second step, the bookdown configuration is set to
render the site in the
docs folder. This is the default folder that GitHub Pages uses to render sites. This is ideal for a single person working on the project,
but it is not ideal for a team of people working on the same project.
For the third step, we make it ideal for a team of people working on the same project. The gh-actions configuration
uses an SSH key that we added to GitHub secrets. This SSH key is used to push the rendered site to the
gh-pages branch, is it stored safely, and users without access to the repository’ secrets will see a 404 page (error page). With the SSH key configured, the
gh-actions configuration clones the
gh-pages branch, then
updates it locally, and then writes the changes to that branch.
With GitHub Pages configured to serve the site from the
gh-pagesbranch in the root folder, the site is updated automatically.
This allows to update https://cienciadedatos.github.io/r4ds/ easily, which we redirect to http://es.r4ds.hadley.nz/ with a CNAME file.