docfx: sync from repo-template (gh-pages bootstrap fix)#150
Merged
Conversation
Sync .github/workflows/docfx.yaml from canonical repo-template to pick up the bootstrap fix from Chris-Wolfgang/repo-template#337. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Note
Copilot was unable to run its full agentic suite in this review.
Syncs the DocFX GitHub Pages deployment workflow with repo-template to fix first-time deployments when the gh-pages branch doesn’t exist yet.
Changes:
- Detects whether
gh-pagesexists and chooses between a worktree-based deploy vs. bootstrapping a fresh repo. - Bootstraps a new
gh-pagesrepo (init + authenticated remote) when the branch is missing to avoid “not a git repository” failures. - Adjusts cleanup to remove either the worktree or the freshly initialized directory, and resets
$LASTEXITCODEafter cleanup.
Reworks the gh-pages deploy block to match repo-template: - Authenticate via `git config http.extraheader` with a base64-encoded `x-access-token:$GITHUB_TOKEN` header instead of embedding the token directly in the remote URL. The plain `https://github.com/owner/repo.git` remote stays out of `git remote -v` output, error messages, and per-repo `.git/config`. - Wrap the entire deploy in `try { ... } finally { ... }`. The finally block always unsets the extraheader so the token cannot linger in the runner's global git config for subsequent steps, even if the try block hits an early `exit` (failed `ls-remote`, missing template). - Distinguish "ls-remote succeeded with empty output (branch missing)" from "ls-remote failed (auth/network)" via `$LASTEXITCODE`, so a transient failure does not silently route into the bootstrap path and clobber an existing gh-pages branch. - Capture `$deployExitCode` before cleanup so cleanup noise cannot mask a real push failure, then explicit `exit` at the end of the script. Addresses the Copilot review comment about token-in-URL on PR #150. The `git init --initial-branch=` form is kept as-is — GitHub-hosted runners ship Git ≥ 2.40 on every supported image, so the Git 2.28 floor is not a concern. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This was referenced Jun 23, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Sync
.github/workflows/docfx.yamlfromrepo-templateto pick up the gh-pages bootstrap fix from Chris-Wolfgang/repo-template#337.What changed
The "Deploy docs to GitHub Pages" step had a latent bug: when the
gh-pagesbranch did not yet exist on the remote,$WORK_DIRwas created as a plain directory and the subsequentgit add/diff --cached/commit/pushfailed withfatal: not a git repository. The fix initializes the directory as a git repo ongh-pagesand adds the authenticatedoriginremote, so the existing add/commit/push works on a first-ever deploy. Cleanup also branches betweengit worktree remove(worktree path) andRemove-Item(fresh-repo path).If
gh-pagesalready exists in this repo (the common case), this change is a no-op at runtime — the bootstrap branch is only taken on a fresh repo.Test plan
gh-pagesis unaffected