[publish] Avoid gh-pages branch creation error when issue is about remote access permission

[mhollanders]

Bug description

I cloned my website to make some changes and when I tried quarto publish gh-pages I get the following errors:

J6M2GFCW45:quantecol-site s447341$ quarto publish gh-pages
? Publish site to https://quantecol.com.au using gh-pages? (Y/n) › Yes
Saved working directory and index state WIP on main: b23d059 test2
fatal: a branch named 'gh-pages' already exists
Your branch is up to date with 'origin/main'.
Already on 'main'
On branch main
Your branch is up to date with 'origin/main'.

I saw here that the issue has apparently been documented but I don't know how to fix it. I'm not savvy enough with Git to dare try and figure it out myself, any tips?

Steps to reproduce

No response

Expected behavior

No response

Actual behavior

No response

Your environment

No response

Quarto check output

No response

[mcanouil]

Go to your local clone and type git branch -d gh-pages.

Or if the above did not solve the issue

Go to GitHub, use the interface to go to the branches panel.
Rename the branch (or delete it).

Go to your clone and remove the gh-pages branch.

[mhollanders]

Thank you very much. I tried that and am now getting these errors:

J6M2GFCW45:quantecol-site s447341$ quarto publish gh-pages
? Publish site to https://quantecol.com.au using gh-pages? (Y/n) › Yes
Saved working directory and index state WIP on main: b23d059 test2
Switched to a new branch 'gh-pages'
[gh-pages (root-commit) fcc012c] Initializing gh-pages branch
remote: Permission to mhollanders/quantecol-site.git denied to mhollanders.
fatal: unable to access 'https://github.com/mhollanders/quantecol-site.git/': The requested URL returned error: 403
Your branch is up to date with 'origin/main'.
Switched to branch 'main'
On branch main
Your branch is up to date with 'origin/main'.

For now the website is offline.

[mcanouil]

Did you configure your Git environment?
Are you identified via HTTPS/SSH?

You need to have access to the repository which means you need to be authentified via Git.

[mhollanders]

I believe it's been configured and I'm identified via HTTPS. This is what my configuration is:

J6M2GFCW45:quantecol-site s447341$ git config --list
credential.helper=osxkeychain
init.defaultbranch=main
user.name=Matthijs Hollanders
user.email=matthijs.hollanders@gmail.com
filter.lfs.required=true
filter.lfs.clean=git-lfs clean -- %f
filter.lfs.smudge=git-lfs smudge -- %f
filter.lfs.process=git-lfs filter-process
core.repositoryformatversion=0
core.filemode=true
core.bare=false
core.logallrefupdates=true
core.ignorecase=true
core.precomposeunicode=true
remote.origin.url=https://github.com/mhollanders/quantecol-site.git
remote.origin.fetch=+refs/heads/:refs/remotes/origin/
remote.origin.fetch=+refs/heads/gh-pages:refs/remotes/origin/gh-pages
remote.origin.fetch=+refs/heads/gh-pages:refs/remotes/origin/gh-pages
remote.origin.fetch=+refs/heads/gh-pages:refs/remotes/origin/gh-pages
remote.origin.fetch=+refs/heads/gh-pages:refs/remotes/origin/gh-pages
branch.main.remote=origin
branch.main.merge=refs/heads/main

When I try to publish again, I'm again getting the error that the gh-pages already exists even though it doesn't exist in the Github interface, and the website is offline.

? Publish site to https://quantecol.com.au using gh-pages? (Y/n) › Yes
Saved working directory and index state WIP on main: b23d059 test2
fatal: a branch named 'gh-pages' already exists
Your branch is up to date with 'origin/main'.
Already on 'main'
On branch main
Your branch is up to date with 'origin/main'.

[mcanouil]

Could you please format your posts for instance using code blocks for code and output?

I don't quite understand your setup.
How is configured your repository for GitHub Pages?
Why do you have docs in your default branch?
Are you sure you are allowed to commit and push branches from your clone?

[mhollanders]

Yes, sorry. I'm confused as well, about everything.

I tried to just re-do the whole thing by creating a new repo on github.com, cloning it to my machine, moving all the documents for the website into the new repo on my machine, and rendering all the pages. Then I ran the code for the instructions here to create a new branch called gh-pages. I then ran quarto publish gh-pages and it's still not working. Sort of running out of options here.

J6M2GFCW45:quantecol s447341$ quarto publish gh-pages
? Publish site to https://mhollanders.github.io/quantecol/ using gh-pages? (Y/n) › Yes
Saved working directory and index state WIP on main: 102ae6b first
fatal: a branch named 'gh-pages' already exists
Already on 'main'
On branch main
Changes not staged for commit:
  (use "git add/rm <file>..." to update what will be committed)
  (use "git restore <file>..." to discard changes in working directory)
        deleted:    CNAME
        modified:   _quarto.yml
        modified:   blog/hmm-in-stan.qmd

no changes added to commit (use "git add" and/or "git commit -a")

[mhollanders]

Now I'm also trying to go through the docs method. I cleared my git credentials by following these instructions from GitHub:

$ git credential-osxkeychain erase
host=github.com
protocol=https
> [Press Return]

Now when I try to push after committing, it asks for username and password. I generated a new (fine-grained) key just to be sure and enter it as my password, but it's still giving me this:

J6M2GFCW45:quantecol s447341$ git push --set-upstream origin main
Username for 'https://github.com': mhollanders
Password for 'https://mhollanders@github.com': 
remote: Permission to mhollanders/quantecol.git denied to mhollanders.
fatal: unable to access 'https://github.com/mhollanders/quantecol.git/': The requested URL returned error: 403
-ne 
J6M2GFCW45:quantecol s447341$ 

[mcanouil]

You need to fix those permissions issues which are the root cause here I believe.

[cderv]

To go back about the original issue

fatal: a branch named 'gh-pages' already exists

This should not happen. Quarto will try to create only a gh-pages branch when none is found. I believe the error is not clear here because we did not catched the real error (which seems to be permission issue).

For context, to determine if we need to create a new branch or not, we do check

git ls-remote --quiet --exit-code  origin gh-pages

Basically, if this is not a success (so bad exit code), quarto will considered that a gh-pages branch does not exists. But this does not assume some permission error while contacting remote I believe.

Running in debug mode before any other fixes would have confirmed us that: [Debug mode opt-in] (https://quarto.org/docs/troubleshooting/#verbose-mode)

If we manage to reproduce to test, we could try adapt the check to handle this problem with a better solution that just trying to create the branch anyway

quarto-cli/src/core/github.ts

Lines 45 to 57 in a604268

	// check for a gh-pages branch
	context.ghPages = (await execProcess({
	cmd: [
	"git",
	"ls-remote",
	"--quiet",
	"--exit-code",
	"origin",
	"gh-pages",
	],
	stdout: "piped",
	stderr: "piped",
	})).success;

For example, we don't check local repo for a branch neither.

So conclusion to me is :

• @mhollanders as explained by @mcanouil you have a permissions problem to solve to understand why your local git environment can't connect to your repo
• Quarto would ideally need to do better catching this type of permissions issue in remote IMO
• Quarto should try to check for local gh-pages before creating it anyway to maybe provide better error message (if previous change is not enough for improved user experience)

[mhollanders]

Hi everyone,

As was alluded the issue was in permissions. I ended up generating a new PAT with all the tick boxes ticked and it did the trick. I got it working with the docs methods and I haven't dared yet to go back to the gh-pages method.

I'm sorry that this wasn't a Quarto issue in the end.

Thank you.