Docs to help with setup of gitpages

[kaiiam]

Unless perhaps I'm missing it somewhere I don't believe the instructions to set up the github pages site for a new linkML project are explained in this repository.

Just adding a few lines about chaining the new repos settings/pages

then doing:

worked for me but I had to find that buried in some unofficial notes from @turbomam. Maybe just having this be formalized somewhere will save the next user some time. Much obliged!

[kaiiam]

I presume also running make deploy is needed?

[kaiiam]

There were also failures in the newly created linkml schema (e.g., https://github.com/kaiiam/mifc/actions/runs/4552698058) due to github actions not having write permission, so I had to fix that in the repo settings as well. Perhaps also something to note in the docs.

[turbomam]

github actions not having write permission

Ah yes. That's not a write permission issue. That an unclean tree issue, and it should be better documented. Or maybe the strategy/implementation needs some changes.

[kaiiam]

Not sure what causes an unclean tree or how I got to it, all I did was follow the steps in this repo's readme file to generate my LinkML project. I pushed it to github as it said to do but there was the issue of the webpage not working and also the write permission causing the action to fail. So I'm just trying to document what I did to get over it, so that others who also might have that issue can know what to do or you can help them fix it.

Could you just add the extra steps needed to the docs so that people don't have to figure it out on their own? Or is there some other fix that can be done as to not need to generate those issues when you use the cookie cutter to create a new linkML project?

[turbomam]

Yes, I will provide some more documentation.

In the mean time: unclean tree: https://discourse.nixos.org/t/what-does-warning-git-tree-a-path-is-dirty-mean-exactly/20568

The solution is usually to commit and push all tracked files. That should solve the problem when running make deploy. I will have to look into the cases in which that error arise from the https://github.com/kaiiam/mifc/blob/main/.github/workflows/deploy-docs.yaml action

[kaiiam]

My issue with github actions was:

remote: Permission to kaiiam/mifc.git denied to github-actions[bot]. fatal: unable to access 'https://github.com/kaiiam/mifc/': The requested URL returned error: 403

which was causing the build to fail, there was a setting that I had to go in and fix something like allow write permission to actions. I had never run into that before (perhaps just my unfamiliarity with github actions), however if this always happens then it could be rectified with a note explaining what permission settings to change for the repo.

[turbomam]

I believe the relevant action log here is https://github.com/kaiiam/mifc/actions/runs/4552278931/jobs/8027412535

[kaiiam]

I think both happened I also meant this one: https://github.com/kaiiam/mifc/actions/runs/4552698058/jobs/8028363735 where there was the error:

INFO - Copying '/home/runner/work/mifc/mifc/site' to 'gh-pages' branch and pushing to GitHub. remote: Permission to kaiiam/mifc.git denied to github-actions[bot]. fatal: unable to access 'https://github.com/kaiiam/mifc/': The requested URL returned error: 403

I was able to "fix" this one by going to https://github.com/kaiiam/mifc/settings/actions and

selecting read and write permissions

I'm pretty sure that's what did it because afterwards I didn't get that error: 403 again.

[dalito]

After #89 it will not longer be necessary to allow "Read and write" for the whole project (as shown in your screenshot). "Read repository ..." will be enough. The PR also adds a note how to configure the project (in README).

[kaiiam]

Thank you very much @dalito! Hopefully this helps future users create new linkML project pages more easily.

Much obliged, Kai