need instructions for configuring GitHub actions on copied repos

[labarba]

I created a new repo using the green "Use this template" button, selecting the gw-ospo org as owner; I chose to copy all branches, but this was not documented.

I soon got an email notification from the new repo, saying: deploy-book: All jobs have failed

On the new repo, I went to the "Actions" tab and noticed that it shows a red X

[deploy-book](https://github.com/gw-ospo/oss-licensing/actions/runs/8862478481/job/24335477998#step:8:24) Creating Pages deployment failed Error: Failed to create deployment (status: 404) with build version 2c361624446f5cf532a5f19939ebdb4557f79896. Ensure GitHub Pages has been enabled: https://github.com/gw-ospo/oss-licensing/settings/pages

Poking on the "Pages" settings of the template repo, I noticed it shows "Source > GitHub Actions" under "Build and deployment" – my new repo did not: changed to that…

It shows: "Use a suggested workflow, [browse all workflows](https://github.com/gw-ospo/oss-licensing/actions/new), or [create your own](https://github.com/gw-ospo/oss-licensing/new/main?filename=.github%2Fworkflows%2F&workflow_template=ci%2Fblank)."

I have no idea how to get GitHub Actions configured or set the workflow. The README should have instructions up top on the fact that the user needs to configure this after copying the template repository, explaining how to do it or linking to the relevant section of documentation from GitHub or JupyterBook.

[labarba]

I went to the "Settings" tab and chose "Pages" from the left navigation menu. On the "Build and deployment" section there, under "Source," I chose "GitHub Actions." But this is not done... there is need to choose a workflow. I don't know how to do that: the link to "create your own" opens an editor with a new .yaml file that has some starter workflow. That's not what we want. We want to somehow choose the existing deploy-book workflow that comes from the repository template. Stuck.

[labarba]

I cloned the repository locally, and made changes to a file included in the JupyterBook (intro.md). This apparently activated the deploy-book workflow, so even though I did not specify the workflow in the previous step, GitHub somehow "found" it. This is a mystery. But good, I suppose. Except the action fails anyway. The error says:

Error: Invalid value for 'PATH_SOURCE': Path 'example-book/' does not exist.

This is because I changed the folder name. I guess I need to update the workflow somewhere. Will investigate. But this needs to be documented in the README of the template.

[labarba]

Changed folder name in one place, made more changes to intro.md and pushed, action failed again, found that path had to be changed in two other places, did that. green checkmark!

[labarba]

What's the URL for the build GitHub pages? Pulled up the jupyter-book-template rendered pages to reverse engineer the URL and found it is https://gw-ospo.github.io/<repo name>/intro.html—this also needs to be documented.

[labarba]

Easier: click the "use your GitHub Pages website" radio button when updating the repository description, found when clicking the gear icon next to About on the right-hand side.