mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-13 06:35:52 +00:00
128 lines
No EOL
5.3 KiB
Markdown
128 lines
No EOL
5.3 KiB
Markdown
# Exercise: Deploy Book Workflow
|
|
|
|
The **Deploy Book Workflow (DBW)** automatically builds and publishes your TeachBook whenever changes are pushed to your repository. If you started your book from the TeachBooks Template, this workflow is already included.
|
|
|
|
With this workflow, readers can see your latest book version online without manual intervention. This exercise will guide you through triggering the workflow, configuring branch-specific builds, and customising deployment options.
|
|
|
|
::::::{topic} Exercise objective
|
|
Can you trigger, configure, and monitor the Deploy Book Workflow to publish your TeachBook automatically?
|
|
::::::
|
|
|
|
|
|
|
|
## Trigger the workflow
|
|
|
|
1. Make a small edit in any page of your book (for example `book/intro.md`).
|
|
2. Commit the change and push it to the `main` branch.
|
|
3. Open the **Actions** tab of your repository. You should see a workflow called *Deploy Book* running.
|
|
4. When it finishes, visit the URL:
|
|
|
|
````
|
|
https://<username>.github.io/<repository-name>/
|
|
````
|
|
|
|
to see the updated book.
|
|
|
|
|
|
5. The workflow can also be triggered in a separate branch. Create a new branch, e.g., `draft-chapter`.
|
|
6. Push a change to this branch.
|
|
7. The DBW automatically builds a version of your book for that branch, available at:
|
|
|
|
````
|
|
https://<username>.github.io/<repository-name>/draft-chapter/
|
|
````
|
|
|
|
```{tip}
|
|
Branch-specific builds are useful for previewing work in progress without affecting the main book.
|
|
```
|
|
|
|
|
|
## Customise the workflow
|
|
|
|
8. The behaviour of the Deploy Book Workflow can be adapted by defining **repository variables** in your GitHub repository, 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).
|
|
|
|
|
|
```{admonition} Key repository variables
|
|
| Variable | Default | Purpose |
|
|
|-----------------------|-------------|-------------------------------------------------------------------------|
|
|
| `PRIMARY_BRANCH` | `main` | Which branch appears at the root URL. |
|
|
| `BEHAVIOR_PRIMARY` | `redirect` | How the root URL behaves: `redirect`, `copy`, or `move`. |
|
|
| `BRANCH_ALIASES` | *(blank)* | Space-separated list of aliases (custom URLs) for branches. |
|
|
| `BRANCHES_TO_DEPLOY` | `*` | Which branches are deployed (all by default). |
|
|
| `BRANCHES_TO_PREPROCESS` | *(blank)* | Branches preprocessed with TeachBooks (e.g. remove draft-only content). |
|
|
| `BRANCHES_ARCHIVED` | *(blank)* | Adds a banner to old versions marking them as archived. |
|
|
```
|
|
|
|
```{note}
|
|
You can also edit `.github/workflows/call-deploy-book.yml` to change which branches or folders trigger deployment.
|
|
```
|
|
|
|
|
|
## Common usage scenarios
|
|
|
|
### Scenario 1 — Academic years
|
|
|
|
```{admonition} Context
|
|
Each year you release a new version of your book for students, but older cohorts still need access.
|
|
```
|
|
|
|
9. Create a branch for each year (e.g. `2024`, `2025`).
|
|
10. In repository variables, set:
|
|
|
|
* `PRIMARY_BRANCH = 2025`
|
|
* `BEHAVIOR_PRIMARY = redirect` (so the root redirects to the current year).
|
|
11. Push a change to the `2025` branch.
|
|
12. Verify the URLs:
|
|
|
|
* `.../my_book/2025/` (this year)
|
|
* `.../my_book/2024/` (last year)
|
|
* `.../my_book/` (redirects to current year).
|
|
|
|
```{tip}
|
|
If you want the root URL to always show a complete book instead of the in-progress year, set
|
|
`PRIMARY_BRANCH = 2024` and `BEHAVIOR_PRIMARY = copy`, and mark `2025` as archived.
|
|
```
|
|
|
|
|
|
### Scenario 2 — Draft and release workflow
|
|
|
|
```{admonition} Context
|
|
You want a public release branch, an internal draft branch, and multiple author branches for parallel work.
|
|
```
|
|
|
|
13. Create branches: `release`, `draft`, `author_1`, `author_2`, etc.
|
|
14. Set your GitHub default branch to `draft`.
|
|
15. In repository variables, set:
|
|
|
|
* `PRIMARY_BRANCH = release`
|
|
* `BEHAVIOR_PRIMARY = copy`.
|
|
16. Push changes to each branch and check the URLs:
|
|
|
|
* `.../my_book/` (release version)
|
|
* `.../my_book/draft/` (draft version)
|
|
* `.../my_book/author_1/`, etc.
|
|
|
|
```{note}
|
|
Making `draft` the default branch ensures pull requests are tested in draft first, avoiding accidental premature releases.
|
|
```
|
|
|
|
|
|
17. When you are ready, commit your changes to the repository by clicking on the green `Commit changes` button.
|
|
|
|
18. Add a commit message.
|
|
|
|
19. To see your changes, go to {octicon}`play` `Actions` - The most recent workflow run `overview.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting).
|
|
|
|
20. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
|
|
|
|
|
|
|
|
```{admonition} Check your understanding
|
|
:class: note
|
|
|
|
|
|
Before moving on, make sure you understand:
|
|
- How can you trigger the Deploy Book Workflow?
|
|
- What is the purpose of `PRIMARY_BRANCH` and `BEHAVIOR_PRIMARY`?
|
|
- How would you set up the workflow so that both a release and a draft version of your book are available online?
|
|
``` |