# 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). 


```{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`      |    | Space-separated list of aliases (custom URLs) for branches.              |
| `BRANCHES_TO_DEPLOY`  | `*`         | Which branches are deployed (all by default).                            |
| `BRANCHES_TO_PREPROCESS` |  | Branches preprocessed with TeachBooks (e.g. remove draft-only content).  |
| `BRANCHES_ARCHIVED`   |   | 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. However, we recommend
using redirects as students might bookmark pages. If the URL changes the next academic year their bookmark
becomes invalid or points to another page.
```


### 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?  
```