chore(ci): update repo homepage after docs deploy

[mabry1985]

Summary

• Writes the deployed GitHub Pages URL back to the repo's homepage field so it renders in the About sidebar.
• Adds administration: write permission so GITHUB_TOKEN can PATCH the repo metadata.

Test plan

• Merge, then confirm the next docs deploy updates the About sidebar automatically.

Summary by CodeRabbit

• Chores
  • Updated GitHub Actions workflow configuration to automatically sync the repository's homepage setting with deployed Pages URL.

[coderabbitai]

Walkthrough

The .github/workflows/docs.yml workflow was modified to add administration: write permission and a new step that patches the repository's homepage field using the GitHub CLI with the deployed Pages URL as input.

Changes

Cohort / File(s)	Summary
GitHub Actions Workflow .github/workflows/docs.yml	Added administration: write permission to top-level permissions. Added post-deployment step using GitHub CLI to patch the repository's homepage field with the deployed Pages URL from steps.deployment.outputs.page_url.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~8 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly and specifically describes the main change: updating the repository's homepage field after a docs deployment via CI workflow.
Description check	✅ Passed	The description covers the required Summary and Test plan sections from the template, providing clear context about what changed and why, though the Test plan checkbox remains unchecked.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/docs-workflow-homepage

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against the current code and only fix it if needed.

Inline comments:
In @.github/workflows/docs.yml:
- Line 13: Replace the invalid permissions key and switch to a proper admin
token: remove the line "administration: write" and instead set only valid
permissions (e.g., "contents: write" or "pages: write" as appropriate) in the
permissions block; then stop using secrets.GITHUB_TOKEN for the PATCH
/repos/{owner}/{repo} call and use a stored personal access token or GitHub App
token with repository admin rights (e.g., secrets.ADMIN_TOKEN or secrets.PAT)
for that step so the homepage update succeeds.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: 04cd1c87-6f84-4445-ab6d-58e6275f968d

📥 Commits

Reviewing files that changed from the base of the PR and between e7a5620 and 9b25fc8.

📒 Files selected for processing (1)

• .github/workflows/docs.yml

[coderabbitai]

⚠️ Potential issue | 🔴 Critical

🧩 Analysis chain

🌐 Web query:

GitHub Actions workflow syntax: is administrationa supported key under top-levelpermissions? Please list the currently supported permission keys from official docs.

💡 Result:

No, administration is not a supported key under the top-level permissions key in GitHub Actions workflow syntax. The supported permission keys, as listed in the official GitHub documentation for workflow syntax, are: - actions - attestations (mentioned in secondary sources) - checks - contents - deployments - discussions - id-token - issues - packages - pages - pull-requests - repository-projects - security-events - statuses Additionally, shorthands like read-all, write-all, and {} (none) are supported. These permissions control access for the GITHUB_TOKEN. The key administration appears in GitHub App permissions or Enterprise contexts but is not available for workflow permissions.

Citations:

• 1: https://docs.github.com/actions/using-workflows/workflow-syntax-for-github-actions
• 2: https://docs.github.com/actions/reference/workflows-and-actions/workflow-syntax
• 3: https://docs.github.com/en/actions/using-jobs/assigning-permissions-to-jobs
• 4: https://docs.github.com/en/actions/reference/github_token-reference
• 5: https://dev.to/pwd9000/fgjgghjgh-19ka
• 6: https://github.github.com/gh-aw/reference/permissions/
• 7: https://pdsinterop.org/docs/development/github-actions/github-actions.permissions
• 8: https://docs.github.com/actions/reference/workflow-syntax-for-github-actions
• 9: https://docs.github.com/en/actions/using-workflows/workflow-syntax-for-github-actions
• 10: https://docs.github.com/en/actions/writing-workflows/workflow-syntax-for-github-actions
• 11: https://github.blog/changelog/2021-04-20-github-actions-control-permissions-for-github_token/

---

🌐 Web query:

For GitHub REST API PATCH /repos/{owner}/{repo}(updatinghomepage), what token type and exact repository permission are required? Does GITHUB_TOKEN from Actions support this operation?

💡 Result:

For the GitHub REST API PATCH /repos/{owner}/{repo} endpoint to update the repository homepage, the token must provide admin access to the repository. This corresponds to the 'repo' OAuth scope for classic personal access tokens or fine-grained tokens, or repository 'Administration' write permission. The endpoint example shows updating 'homepage' without explicit permission notes beyond admin for certain fields like security_and_analysis, but deleting the repo explicitly requires admin, and repo updates generally require admin permissions. The GITHUB_TOKEN from GitHub Actions does not support this operation with standard permissions. GITHUB_TOKEN has limited scopes equivalent to specific granular permissions (contents:write, issues:write, etc.), but lacks 'Administration' write permission needed for repository settings updates like homepage. StackOverflow confirms GITHUB_TOKEN cannot perform repository settings changes, requiring a PAT or GitHub App with broader access. Permissions can be set in workflows, but repository administration is not among available GITHUB_TOKEN permissions.

Citations:

• 1: https://docs.github.com/en/rest/repos/repos
• 2: https://docs.github.com/rest/repos/repos
• 3: https://docs.github.com/en/rest/repos/repos?apiVersion=2026-03-10
• 4: https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens?apiVersion=2026-03-10
• 5: https://stackoverflow.com/questions/77693765/github-actions-token-permissions-to-change-repository-settings
• 6: https://docs.github.com/actions/reference/authentication-in-a-workflow

---

Remove invalid permission scope and use appropriate token for repository admin operation.

Line 13 uses administration: write, which is not a valid GitHub Actions permissions key (only: actions, attestations, checks, contents, deployments, discussions, id-token, issues, packages, pages, pull-requests, repository-projects, security-events, statuses). Additionally, lines 44-46 attempt to use secrets.GITHUB_TOKEN for PATCH /repos/{owner}/{repo}, which requires admin-level repository permission that GITHUB_TOKEN cannot grant. The workflow will fail at validation and/or return 403 at runtime.

Replace administration: write with a valid permission or remove if unneeded, and use a personal access token or GitHub App token with admin repository access for the homepage update operation.

🧰 Tools

🪛 actionlint (1.7.12)

[error] 13-13: unknown permission scope "administration". all available permission scopes are "actions", "artifact-metadata", "attestations", "checks", "contents", "deployments", "discussions", "id-token", "issues", "models", "packages", "pages", "pull-requests", "repository-projects", "security-events", "statuses"

(permissions)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In @.github/workflows/docs.yml at line 13, Replace the invalid permissions key
and switch to a proper admin token: remove the line "administration: write" and
instead set only valid permissions (e.g., "contents: write" or "pages: write" as
appropriate) in the permissions block; then stop using secrets.GITHUB_TOKEN for
the PATCH /repos/{owner}/{repo} call and use a stored personal access token or
GitHub App token with repository admin rights (e.g., secrets.ADMIN_TOKEN or
secrets.PAT) for that step so the homepage update succeeds.