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¶
WIP
find the file
identify the trigger
describe the environment created
itendify the steps
Observe it¶
WIP
make a commit to the repo
visit the Actions tab
observe the workflow running
dig deeper
Break it¶
WIP
introduce an error
observe the failure
fix the error
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.
WIP
add to workflow file
commit, push, observe
quiz quetsion: what is the date?! file edited, time of commit, time of push, other?... answer = whenever the first line in the code snippet below is executed in the cloud (e.g., time of push + time to set up venv and start build).
- 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.ymldate: ${BUILD_DATE}