From bd4ab64fb26b95f27a7778ef6084953b5a37be5c Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Mon, 17 Jun 2024 08:22:08 +0200 Subject: [PATCH] Added option for private repo as a result from https://github.com/TeachBooks/deploy-book-workflow/pull/42 --- README.md | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/README.md b/README.md index 40a6726..11ac06a 100644 --- a/README.md +++ b/README.md @@ -21,8 +21,8 @@ The template allows you to start your own Jupyter Book and hosting that book onl How to use the template is demonstrated in the figure below, all steps are elaborated on in the following step-by-step tutorial. -![template-demo](figures/teachbooks-template.gif) -The demonstration is also available as a video [here](https://youtu.be/nN3Oi_MVvF0). +![template-demo-public](figures/teachbooks-template.gif) +The demonstration for a public repository is also available as a video [here](https://youtu.be/nN3Oi_MVvF0). 1. To get started making your Jupyter Book with our functionalities, use the [template book](https://github.com/TeachBooks/template) as template: @@ -32,17 +32,19 @@ The demonstration is also available as a video [here](https://youtu.be/nN3Oi_MVv ![create_new_repository](figures/create_new_repository.png) -3. You need to activate GitHub pages so that your website is published to the internet. As long as you don't do this your book is not published online. Actually, now that you've taken this template our workflow tries to publish it to GitHub pages, which you didn't have the chance to activate yet. That's why you probably received an email with 'call-deploy-book: Some jobs were not successful' and you see the failed job under `Actions` - `All workflows` - `call-deploy-book` - `Initial commit`. You can activate GitHub pages by setting the source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: +3. You can choose for `Private` only if you've GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server. Otherwise, you won't be able to publish your book online. + +4. (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`). + +5. You need to activate GitHub pages so that your website is published to the internet. As long as you don't do this your book is not published online. Actually, now that you've taken this template our workflow tries to publish it to GitHub pages, which you didn't have the chance to activate yet. That's why you probably received an email with 'call-deploy-book: Some jobs were not successful' and you see the failed job under `Actions` - `All workflows` - `call-deploy-book` - `Initial commit`. You can activate GitHub pages by setting the source for GitHub pages to GitHub Actions under `Settings` - `Pages` - `Build and deployment` - `Source` - `GitHub Actions`: ![Activate pages](figures/set_up_pages.png) -4. Make an edit to the book by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`). Now checkout the progress of the publishing workflow under `Actions` - `All workflows` - `call-deploy-book` -``. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from `Actions` - `All workflows` - `call-deploy-book` - `Initial commit` - `Re-run all jobs` - `Re-run jobs`: +6. Make an edit to the book by editing and committing changes to one of the files in the `book/` subdirectory (available under `Code`). Now checkout the progress of the publishing workflow under `Actions` - `All workflows` - `call-deploy-book` -``. Remember, the first commit which is there has failed because GitHub Pages wasn't activated at the time of `Initial commit`, you could also re-run that job if you don't want to make an edit. You can do so by running the workflow from `Actions` - `All workflows` - `call-deploy-book` - `Initial commit` - `Re-run all jobs` - `Re-run jobs`: ![Action](figures/action_re-run.jpeg) -5. When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. These links are visible in the action's summary as well, as shown in the figure of step 4. +7. When the workflow has finished, visit your build book at `https://.github.io/` (case sensitive). For our example it is [https://dummydocent.github.io/test_book_from_template/](https://dummydocent.github.io/test_book_from_template/) for the shown repository. These links are visible in the action's summary as well, as shown in the figure of step 4. Additional tip: Set the repository website as your GitHub Pages website under