Closed gerteck closed 3 days ago
Hi @gerteck thanks for the PR! I love the detailed testing :) For others' reference if they want to check:
permissions:
deployments: write
permissions:
contents: write
One thing I want to discuss is the renaming of the default branch.
Right now, our documentation uses master
since this renaming of default branch only occurred recently.
I think there might be a need to either refactor the rest of the documentation to use main
or at least refactor the rest of this deployment page.
Either that, or we can just stick to master
.
One thing I want to discuss is the renaming of the default branch.
Right now, our documentation uses
master
since this renaming of default branch only occurred recently. I think there might be a need to either refactor the rest of the documentation to usemain
or at least refactor the rest of this deployment page. Either that, or we can just stick tomaster
.
Oh yes, that is definitely true. I could update it across the page and/or documentation. Alternatively, sticking to master
sounds good too, and to supplement, a tip box could be added to change the default branch to main
if needed.
Oh yes, that is definitely true. I could update it across the page and/or documentation. Alternatively, sticking to
master
sounds good too, and to supplement, a tip box could be added to change the default branch tomain
if needed.
Yup, keeping it as master
(to limit the scope of the PR) and adding a tip info box to alert the reader about the branch name (so that the reader doesn't overlook it) seems reasonable.
Hi @gerteck thanks for the change!
I think it might be better to put the tip box further up the page, just in case a user tries to use the other configurations and doesnt see the tip box, since it is currently only under deploying under github actions.
Im thinking right before Using the markbind deploy command
. What do you think?
Hi @gerteck thanks for the change! I think it might be better to put the tip box further up the page, just in case a user tries to use the other configurations and doesnt see the tip box, since it is currently only under deploying under github actions. Im thinking right before
Using the markbind deploy command
. What do you think?
I was wondering about that, the info box is relevant to some of the other configurations too! Thanks for pointing it out!
Roughly around line 40, before Using the markbind deploy command
. Sounds good!
I think the solution is elegant and the updates in documentation are clear.
However, when I try this workflow myself, although I see success in workflow run log, the website is not deployed unless I manually enabled github pages. I wonder if this is the desired behaviors or is the workflow supposed to automatically set up the github pages?
However, when I try this workflow myself, although I see success in workflow run log, the website is not deployed unless I manually enabled github pages. I wonder if this is the desired behaviors or is the workflow supposed to automatically set up the github pages?
I encountered a similar issue with the docs of another project. So, it is possible that enabling gh-pages manually wasn't needed when the doc was written but it became necessary later due to a change on GitHub side. Anyway, if it is confirmed as a required step, best to add that into the docs.
However, when I try this workflow myself, although I see success in workflow run log, the website is not deployed unless I manually enabled github pages. I wonder if this is the desired behaviors or is the workflow supposed to automatically set up the github pages?
I encountered a similar issue with the docs of another project. So, it is possible that enabling gh-pages manually wasn't needed when the doc was written but it became necessary later due to a change on GitHub side. Anyway, if it is confirmed as a required step, best to add that into the docs.
I did some testing regarding this as well, and face the same issue, when deploying via Github Actions for the first time without manually enabling it. However, one workaround I found was to run markbind deploy
, as it pushes the generated site to gh-pages
directly, and triggers the page deployment., and automatically sets up github pages. Subsequent pushes to main work as per normal.
(I did however, face issue #2547 when doing markbind deploy
, adding on to it, I tried running set CACHE_DIR=cache
in vs-code's internal terminal, which didn't work, but I realised I had to run the terminal from outside of vs-code for the remedy to work)
I searched online, and it seems to be a known issue, and enabling it manually on the repo settings tabs seems to be a required step, although I could not find out the specifics: https://github.com/marketplace/actions/github-pages-action#%EF%B8%8F-first-deployment-with-github_token
Agree that some information could be added into the docs regarding this, although I am not sure how I would word it specifically.
Hi @gerteck,
Thank you for your detailed research and updates on the GitHub Actions workflow. Your thorough testing and documentation improvements are greatly appreciated.
Given your findings, it's clear that manual enabling of GitHub Pages might still be a necessary step for first-time deployments, even though the workflow runs successfully. This is valuable information that should be included in our documentation to prevent confusion for users.
I think you can proceed with updating the docs to include this step. You've already done a great job with your research and you'll certainly find an appropriate way to word this in the documentation.
Given your findings, it's clear that manual enabling of GitHub Pages might still be a necessary step for first-time deployments, even though the workflow runs successfully
Manual enabling has been necessary since way back. We have this line in our docs:
Then, navigate to the Settings > Pages section on GitHub for that repository and set the source to the root of the gh-pages branch. You can read this source on GitHub Pages for more details.
When the user does that, he/she will hence enable GitHub pages.
This point is also included in our MarkBind Action readme:
Token for GitHub Pages Simply use ${{ secrets.GITHUB_TOKEN }} Note that you need to ensure that you have selected the branch that you want to deploy to in your GitHub repo's Pages settings
But yes, we can improve the docs to highlight this point.
Welcome, @gerteck! 🎉 Thank you for your contribution to the MarkBind project!
@Tim-Siu, please remember to add @gerteck as an official contributor to our repository.
See the full list of contributors here. ✨
@Tim-Siu Each PR must have a SEMVER impact label, please remember to label the PR properly.
@all-contributors please add gerteck for code, doc
@Tim-Siu
I've put up a pull request to add @gerteck! :tada:
What is the purpose of this pull request?
Overview of changes: Resolves #2555
Flips github_token permissons to write contents.
Due to the updating of default GITHUB_TOKEN permissions to read-only (2023), the sample workflow code no longer works out of box without content write permissions to write to
gh-pages
branch. ~Additionally, renamed default branch tomain
accordingly to make it easier to get started.~ Added Info box to replacemaster
withmain
if applicable.Anything you'd like to highlight/discuss:
Testing instructions:
Tested a few scenarios to try to figure out the least permissive configuration.
Proposed commit message: (wrap lines at 72 characters)
Update Sample Workflow Permissions
Due to the updating of default GITHUB_TOKEN permissions to read-only, updating of sample workflow code needed to work out of box. Additionally, branch name has been updated accordingly to main make it easier to get started.
Checklist: :ballot_box_with_check:
Reviewer checklist:
Indicate the SEMVER impact of the PR:
At the end of the review, please label the PR with the appropriate label:
r.Major
,r.Minor
,r.Patch
.Breaking change release note preparation (if applicable):