Deploy Book Workflow

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.

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#

  1. The behaviour of the Deploy Book Workflow can be adapted by defining repository variables in your GitHub repository, as explained here.

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#

Context

Each year you release a new version of your book for students, but older cohorts still need access.

  1. Create a branch for each year (e.g. 2024, 2025).

  2. In repository variables, set:

  • PRIMARY_BRANCH = 2025

  • BEHAVIOR_PRIMARY = redirect (so the root redirects to the current year).

  1. Push a change to the 2025 branch.

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

Context

You want a public release branch, an internal draft branch, and multiple author branches for parallel work.

  1. Create branches: release, draft, author_1, author_2, etc.

  2. Set your GitHub default branch to draft.

  3. In repository variables, set:

  • PRIMARY_BRANCH = release

  • BEHAVIOR_PRIMARY = copy.

  1. 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.

  1. When you are ready, commit your changes to the repository by clicking on the green Commit changes button.

  2. Add a commit message.

  3. To see your changes, go to 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).

  4. Do you see your change? If you don’t see it click CTRL+F5/Control+F5to refresh the page.

Check your understanding

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?

Contents