# GitHub reusable action: publish your book online to GitHub Pages
```{admonition} User types
:class: tip
This page is useful for user type 3, 4 and 5.
```
We developed a workflow which builds your TeachBook in your repository for all branches and publishes them online via GitHub Pages. In simplified terms, it builds the website based on your repository.
The [TeachBooks Template](https://github.com/TeachBooks/template) uses this functionality for example. The workflow `call-deploy-book.yml` calls the `deploy-book.yml` workflow, which builds the Jupyter books at the calling repository for all branches, and deploys them via GitHub Pages.
The workflow has the following features:
- Releasing of your [TeachBook](https://teachbooks.tudelft.nl/)-repository (built with [Jupyter Book](https://github.com/executablebooks/jupyter-book)) to GitHub Pages
- Ability to release both private (GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server required) and public (GitHub Free is enough) repositories.
GitHub Teams is free for teachers as described in the [GitHub documentation](https://docs.github.com/en/education/explore-the-benefits-of-teaching-and-learning-with-github-education/github-education-for-teachers/about-github-education-for-teachers#github-education-features-for-teachers).
If you have an organization for your TeachBook on GitHub, link your GitHub team rights to your organization as described on the [GitHub website](https://github.com/team#organizations).
- Releasing all or a selection of branches, allowing to build a draft version of the TeachBook online which reduces the need for local builds of the book
- Provides a summary describing where the TeachBook is released, errors in the build process per branch and how the release step is configured
- Caching of already built books so that it can be partially reused when another branch is released or the next build contains critical errors
- Caching of python environment to speed up the workflow
- Allowing to use submodules within your book
- Customizable trigger for the workflow itself
- Optionally preprocess branches using the [`teachbooks` package](https://github.com/TeachBooks/TeachBooks).
- Converting branch-names to well-defined URLs
- Customizable settings on where the books should be deployed including alias for branch-names and selection of one branch to be deployed on root. The workflow will gives warnings if these settings are ill-defined or conflicting. Although aliases are not allowed by GitHub Pages, it seems you can use one alias, but not more.
- Redirects the root directory to one of the branches or copies one of the branches to root.
- Adds an 'archived'-banner to old branches / branches of previous years.
## How to start using this workflow
As previously mentioned, this workflow is used in `TeachBooks/template`. Feel free to use it for your TeachBook as well:
1. Add [`teachbooks`](https://github.com/TeachBooks/TeachBooks) to your `requirements.txt` file in your root folder
2. Move all the TeachBook files (including `_config.yml` and `_toc.yml`) to a subdirectory `book/`.
3. Copy the [`call-deploy-book.yml`](https://github.com/TeachBooks/deploy-book-workflow/blob/main/.github/workflows/call-deploy-book.yml) workflow to the `/.github/workflows` folder in your repository.
4. Set source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions` (as long as you don't do this the workflow deploys all branches which build successfully).
5. (Only required for private repositories) Create a Personal Access Token (classic) with at least the scopes `repo`, `read:org` and `gist` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` (`Settings` > `Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`.)
6. Trigger the workflow by making an edit to the TeachBook by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`) or manually activating the workflow under `Actions` - `All workflows` - `call-deploy-book` - `Run workflow` - `Use workflow from branch: ` - `Run workflow` (this workflow).
7. Now checkout the progress and summary of the releasing workflow under `Actions` - `All workflows` - `call-deploy-book` -``.
## Customize the workflow: TeachBook releasing settings
You can adapt the behaviour by setting repository variables as explained [here](https://docs.github.com/en/actions/learn-github-actions/variables#creating-configuration-variables-for-a-repository) or using the [VS Code Extension GitHub Actions](https://marketplace.visualstudio.com/items?itemName=GitHub.vscode-github-actions). Define the following repository variables:
- `PRIMARY_BRANCH` which is set to `main` whenever it's not defined in the repository variables.
- This sets the branch or alias (when using 'redirect' for `BEHAVIOR_PRIMARY`) which is shown on root.
- It is advised to show your most recent branch on root.
- `BEHAVIOR_PRIMARY` which is set to `redirect` whenever it's not defined in the repository variables.
- This indicates whether to copy the PRIMARY_BRANCH to root ('copy') or redirect from root to the PRIMARY_BRANCH ('redirect')
- Advised to use 'redirect' if you expect to archive a version in the future so that the URL doesn't change for the reader.
- `BRANCH_ALIASES` which is set to ` ` (just a space) whenever it's not defined in the repository variables.
- This defines an alias (custom URL) for a branch
- Variables should be a space-separated list of branch names, e.g. 'alias:really-long-branch-name`
- If no alias is wanted, `BRANCH_ALIASES` may be set to ` ` (just a space)
- `BRANCHES_TO_DEPLOY` which is set to `*` (all branches) whenever it's not defined in the repository variables.
- This defines the branches to deploy.
- It should be a space-separated list of branch names, e.g. 'main second third'.
- `BRANCHES_TO_PREPROCESS` which is to to ` ` (just a space = no branch) whenever it's not defined in the repository variables
- This defines the branches to preprocess with the [`TeachBooks` package](https://teachbooks.github.io/TeachBooks/cli/cli.html#cmdoption-teachbooks-build), which removed book-pages and config lines defined with `# START REMOVE FROM RELEASE` and `# END REMOVE FROM RELEASE`
- It should be a space-separated list of branch names, e.g. 'main second third'.
- If no preprocessing is required, `BRANCH_TO_PREPROCESS` may be set to ' ' (space).
- `BRANCHES_ARCHIVED` which is set to ` ` (space, no branch) whenever it's not defined in the repository variables
- This adds a banner to the released branch: You are viewing an archived version of the book. Click here for the latest version.
- It should be a space-separate list of branch names, e.g. 'main second third'.
In `call-deploy-book.yml` itself you can specify the trigger for this workflow. By default, a push to any branch triggers the workflow. You can limit the branches or subdirectories.
## View the workflow progress and summary
Whenever the workflow is triggered, its progress and a summary can be seen under the `Actions`- `All workflows` - `call-deploy-book` in GitHub! It shows you a descriptive summary:
- Ill-defined repository configuration variables (in `Annotations`)
- Which branches are released and where (`https://.github.io/` (case sensitive)) including which branch is released on the website root and the applied alias
- Errors in the build process
- How the repository variables are defined during the build.
Here's an example for a summary for the template book:
> ### Branches deployed
> | Branch 🎋 | Link 🔗 | Build status ☑️ |
> | :--- | :--- | :--- |
> | main | [https://teachbooks.github.io/template/main](https://teachbooks.github.io/template/main) | ✅ `Released` |
> | version2 | [https://teachbooks.github.io/template/version2](https://teachbooks.github.io/template/version2) | 🔴 `Build failed [1]` |
> | version3 | [https://teachbooks.github.io/template/version3](https://teachbooks.github.io/template/version3) | ⭕ `Build failed [2]` |
>
> #### Legend for build status
> ✅ `Released` - build success, new version released.
>
> 🔴 `Build failed [1]` - build failure, previous version of the book reused.
>
> ⭕ `Build failed [2]` - build failure, no previous version reused.
>
> #### Primary book at root
> The book at the website root redirects to the primary branch `main` (status: ✅ `Released`).
>
> ### Aliases
> | Alias ➡️ | Target 🎯 | Link 🔗 | Build status ☑️ |
> | :--- | :--- | :--- | :---- |
> | draft | main | [https://teachbooks.github.io/template/draft](https://teachbooks.github.io/template/draft) | ✅ `Released` |
>
> ### Preview of build errors & warnings
> For more details please see the corresponding `build-books` jobs in the left pane.
>
> On branch `version2`:
> ```
> �[91m/home/runner/work/template/template/book/some_content/overview.md:5: WARNING: Non-consecutive header level increase; H1 to H3 [myst.header]�[39;49;00m
> ```
>
> On branch `version3`:
> ```
> /home/runner/work/_temp/ff8c8325-8d8b-4c0b-a2b2-32d2169c55bc.sh: line 8: teachbooks: command not found
> ```
>
> ### Repository configuration variables
> Variables can be set at
>
> ```
> PRIMARY_BRANCH=main (default value used)
> BRANCH_ALIASES=draft:main
> BRANCHES_TO_DEPLOY=* (default value used)
> BRANCHES_TO_PREPROCESS=main
> BEHAVIOR_PRIMARY=redirect (default value used)
> BRANCHES_ARCHIVED= (default value used)
> ```
## Contribute
This tool's repository is stored on [GitHub](https://github.com/TeachBooks/deploy-book-workflow). The `README.md` of the branch `manual_docs` is also part of the [TeachBooks manual](https://teachbooks.tudelft.nl/jupyter-book-manual/external/deploy-book-workflow/README.html) as a submodule. If you'd like to contribute, you can create a fork and open a pull request on the [GitHub repository](https://github.com/TeachBooks/deploy-book-workflow). To update the `README.md` shown in the TeachBooks manual, create a fork and open a merge request for the [GitLab repository of the manual](https://gitlab.tudelft.nl/interactivetextbooks-citg/jupyter-book-manual). If you intent to clone the manual including its submodules, clone using: `git clone --recurse-submodules git@gitlab.tudelft.nl:interactivetextbooks-citg/jupyter-book-manual.git`.