GitHub goal delivery: convert repo from GitLab to GitHub

[johnnygreco]

Goal

Convert NVIDIA/OpenShell-Research from GitLab-oriented repository automation to GitHub-native automation. The repository now uses GitHub Actions for CI, deploys the Zensical documentation site through GitHub Pages, has no active GitLab CI configuration, and has verified Pages deployment evidence.

Shared Context

The repository is a private GitHub repo at https://github.com/NVIDIA/OpenShell-Research with default branch main. The docs site is Zensical-based: sources live under docs/, zensical.toml configures the site, requirements-docs.txt pins zensical==0.0.44, and scripts/build-docs.sh creates .venv-docs, installs docs requirements, runs scripts/render-dev-notes.py, then runs zensical build --clean --strict. The active workflow is .github/workflows/docs.yml. It validates docs builds on every pull request and main push, and deploys site/ to GitHub Pages only from main pushes or manual dispatches on main. GitHub Pages is enabled with build_type=workflow at https://psychic-adventure-4zpjp44.pages.github.io/. The Pages site is private (public=false), so unauthenticated requests redirect to GitHub Pages auth with x-pages-private: 1. Backward compatibility with GitLab CI was not required.

Definition of Done

• GitLab CI configuration is removed or made obsolete by GitHub-native automation; no user-facing repository guidance still says GitLab CI is the docs deployment path.
• GitHub Actions validates docs builds on pull requests and direct main pushes.
• GitHub Actions deploys the generated site/ output to GitHub Pages from main.
• Repository documentation explains the GitHub Actions/GitHub Pages docs workflow and local docs build/preview commands.
• GitHub Pages is configured for the repo and the deployed docs URL is active.
• The deployed docs artifact is smoke-tested for the homepage, Dev Notes listing, one Dev Note post, brand/favicon assets, search/runtime pages, and expected generated bylines/cards.
• All implementation PRs were independently reviewed, required checks passed, and PRs merged in dependency order.

Validation Strategy

Commands/evidence used across the implementation issues:

• test: python3 scripts/render-dev-notes.py
• lint: python3 -m py_compile scripts/render-dev-notes.py
• build: scripts/build-docs.sh
• stale GitLab scan: rg -n "gitlab|GitLab|\.gitlab-ci|gitlab\.io" README.md docs zensical.toml scripts .github || true
• local site smoke: served site/ locally and requested key pages/assets with HTTP 200 checks
• deployment smoke: inspected Pages settings, Actions run status, deployment status, private live URL auth behavior, and exact deployed github-pages artifact contents

Risks

• The GitHub Pages site is private because the repository is private. Tokenless HTTP checks cannot inspect post-auth page content; they correctly receive a 302 to GitHub Pages auth with x-pages-private: 1. Functional content verification used the successful Pages deployment plus the exact github-pages artifact downloaded from the successful main workflow run.
• The workflow uses current GitHub-owned action majors checked through the GitHub API on 2026-06-24: actions/checkout@v7, actions/setup-python@v6, actions/configure-pages@v6, actions/upload-pages-artifact@v5, and actions/deploy-pages@v5.

Issue Checklist (dependency order)

• Add GitHub Actions CI and Pages deployment #3 Add GitHub Actions CI and Pages deployment
• Update repository docs for GitHub-native workflow #4 Update repository docs for GitHub-native workflow
• Verify live GitHub Pages deployment end to end #5 Verify live GitHub Pages deployment end to end

Integration Notes

PR #6 added .github/workflows/docs.yml, removed .gitlab-ci.yml, and updated the README workflow entry. PR #7 expanded the README documentation workflow guidance. After PR #6 merged, Pages was enabled through the API with build_type=workflow. The final main workflow run after PR #7 deployed successfully.

Final Status

Complete as of final main commit f95d97365154f4bc83a39ad5fb514d938bd20b50.

Final evidence:

• PR Add GitHub Actions docs workflow #6 merged as 7b1bf60; PR check passed and independent panel review was clean after one accepted README handoff fix.
• PR Document GitHub docs workflow #7 merged as f95d973; PR check passed and independent reviewers returned clean.
• Latest main Docs run 28121432309 for f95d97365154f4bc83a39ad5fb514d938bd20b50 completed successfully.
• Latest Pages deployment 5185802408 is success with environment_url=https://psychic-adventure-4zpjp44.pages.github.io/.
• Pages API reports build_type=workflow, source=main /, and public=false.
• Unauthenticated live requests to the homepage and brand asset return 302 to GitHub Pages auth with x-pages-private: 1, matching private Pages behavior.
• The exact deployed github-pages artifact from run 28121432309 was downloaded, extracted, served locally, and smoke-tested with HTTP 200 for /, /dev-notes/, /dev-notes/posts/2026-06-05-making-dev-notes-repeatable/, /research/runtime/, /assets/brand/favicon.svg, and /search.json.
• Artifact content checks found OpenShell Research homepage content, Dev Notes cards, post byline, search index content, search worker asset, and brand assets.
• Final holistic reviewers returned clean for CI/deployment integration and documentation-site functionality.

[johnnygreco]

Progress update after issue #3: PR #6 merged as 7b1bf60. The new Docs workflow passed on the PR head 14cf440 with deploy skipped for pull_request. After merge, GitHub Pages was enabled via the API with build_type=workflow at https://psychic-adventure-4zpjp44.pages.github.io/. The main push workflow run 28121113687 completed successfully for 7b1bf60, including the Pages deploy path.

[johnnygreco]

Progress update after issue #4: PR #7 merged as f95d973. README now documents local preview, the canonical scripts/build-docs.sh build, PR validation, and GitHub Pages deployment from main/manual main dispatch. PR #7 validation passed and independent reviewers returned clean.

[johnnygreco]

Closing tracker: all dependency-ordered issues are complete (#3, #4, #5), PRs #6 and #7 are merged, final main run 28121432309 succeeded, Pages deployment 5185802408 succeeded, and final holistic review returned clean. The Pages site is private and available at https://psychic-adventure-4zpjp44.pages.github.io/ for authorized users.