You may be familiar with GitHub Actions: it is a widely used continuous integration tool which can easily and automatically publish your Jupyter Book as a website. This lesson is designed to get you familiar with GitHub Actions in your Jupyter Book and learn how to manipulate them.
What is GitHub Actions?
If you have no idea, or are confused what an Action is, don’t despair! The most simple explanation is that GHA is a tool for automating workflows. For our purposes, everything you need to know is described in this dropdown tip.
“GitHub Actions” is GitHub’s product name for its Continuous Integration / Continuous Deployment (CI/CD) services: if this term is unfamiliar, it’s not important, as you can simply think of CI/CD and GH Actions as an algorithm that can be carried out on your GitHub repository automatically. It is the “workflow automation” framework that sometimes seem like magic to the outside observer.
Within GHA, “workflows” are defined using .yml files in the .github/workflows folder of a repository.
Each workflow can be triggered by one or more events, for example, a commit is pushed to the repository.
Each workflows can have multiple steps (e.g. install software, build the book, deploy the book), and as many steps are repeated, it is possible to find pre-built “actions” in an online marketplace.
In addition, workflows can include arbitrary code (e.g., bash or Python scripts).
GHA is generally free for public repositories, with some limitations on usage for private repositories.
By the end of this workshop you will read and modify workflow files to customize the build and deployment of your Jupyter Book.
Read it¶
In your folder of the repository there is a hidden folder called .github, and inside that is another folder called workflows.
Inside that folder is a file called deploy.yml (or similar).
This file defines the workflow that builds and deploys your Jupyter Book to GitHub Pages.
Observe it¶
Now that you have seen the “steps” of the workflow, it is good to see them “in action” in the Browser.
Understanding where this information is available in your repository is especially useful when debugging problems with your website and PDF build. It is also important to know that this is where you can search for error logs (in the CLI), especially when problems may not occur in your local setup, but your website is not deploying properly.
Break it¶
To make sure you know what a “problem” looks like, we can intentionally break the workflow.
Change it¶
Here we will modify the workflow to add a new feature: automatically updating the “last edited” date in our published book.
The following bash script will modify date: field in the myst.yml file:
- name: Add current date to myst.yml
shell: bash
run: |
BUILD_DATE="$(date +'%Y-%m-%d')"
sed -i "s|\${BUILD_DATE}|${BUILD_DATE}|g" myst.yml
echo "myst.yml:"
grep -nE '^\s*date:' myst.ymlIn addition, this simple script requires setting ${BUILD_DATE} for the date field value in myst.yml.