Upstream Bug: release workflow cannot rename default branch (for now)

[zkamvar]

The release workflow cannot rename the default branch because of a regression in behaviour for GitHub Fine-Grained tokens (see my discussion comment on GitHub's request for comments).

This is during the first phase of the transition so the upstream repository is not affected:

── Setting up repository ─────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────
ℹ Writing to /home/zhian/Documents/Carpentries/Git/carpentries/lesson-transition/release/fishtree-attempt/znk-transition-test/config.yaml
→ created:  -> created: '2023-08-02'
Running git add config.yaml
Running git commit --amend --no-edit
[main 13d9647] [automation] final workbench updates
 Date: Wed Aug 23 09:37:56 2023 -0700
 2 files changed, 3 insertions(+), 64 deletions(-)
 delete mode 100644 .github/workflows/workbench-beta-phase.yml
ℹ renaming default branch (gh-pages) to legacy/gh-pages
POST /repos/fishtree-attempt/znk-transition-test/branches/gh-pages/rename
Error in `gh::gh()`:
! GitHub API error (403): Resource not accessible by personal access token
ℹ Read more at <https://docs.github.com/rest/branches/branches#rename-a-branch>
Backtrace:
    ▆
 1. └─global setup_github(...)
 2.   └─gh::gh(RENAME, new_name = glue::glue("legacy/{default}"), .token = .token)
 3.     └─gh:::gh_make_request(req)
 4.       └─gh:::gh_error(resp, error_call = error_call)
 5.         └─cli::cli_abort(...)
 6.           └─rlang::abort(...)
Execution halted
make: *** [Makefile:106: release/fishtree-attempt/znk-transition-test.json] Error 1

Upstream repository status

Because the error occurs on the first API call, the upstream repository is not affected.

Local status

There will be a local copy of the transitioned repository and the transition hash records:

release/fishtree-attempt/znk-transition-test-commit-map.hash
release/fishtree-attempt/znk-transition-test-ref-map.hash
release/fishtree-attempt/znk-transition-test-status.json
release/fishtree-attempt/znk-transition-test-suboptimal-issues.hash
release/fishtree-attempt/znk-transition-test.hash

Moving forward

It is possible to recover from this and to continue the remote transition manually by doing the following:

0. run cd release/[ORG]/[REPO]/ to move into the transitioned repository (replace [ORG] and [REPO] with the org and repo name you are looking to transition).
1. (on GITHUB) rename gh-pages to legacy/gh-pages (if main is your default, then also rename that to legacy/main)
2. (on GITHUB) enable github actions to run
3. (in local) run git fetch --prune origin
4. (in local) ensure your remote origin is the correct URL
5. (in local) create an orphan gh-pages branch that contains a workflow that will close all PRs to that branch and force-push it up

   git checkout --orphan gh-pages
   git rm -rf .
   mkdir -p .github/workflows/
   curl -o .github/workflows/close-pr.yaml https://raw.githubusercontent.com/carpentries/lesson-transition/main/close-pr.yaml
   git add .github/workflows/close-pr.yaml
   git commit --allow-empty -m "Initializing gh-pages branch"
   git push --force origin HEAD:gh-pages
   git switch main
   

6. (in local) run git switch main && git push --force --set-upstream origin main
7. (on GITHUB) set the main branch to be the default
8. (on GITHUB) (optional) add branch protection to the main branch (to prevent people from accidentally force-pushing)
9. (on GITHUB) lock all branches that start with legacy/
10. (on GITHUB) when the "01 Build and Deploy" workflow finishes running, go to settings/pages and then switch pages to build from the gh-pages branch. When that is complete, your new site will be available in about 20 seconds.