Skip to content

docs(jupyterhub): document GitHub App team sync config#126

Merged
KerwinTsaiii merged 1 commit into
docsfrom
docs-github-app-team-sync-config
Jun 11, 2026
Merged

docs(jupyterhub): document GitHub App team sync config#126
KerwinTsaiii merged 1 commit into
docsfrom
docs-github-app-team-sync-config

Conversation

@MioYuuIH

@MioYuuIH MioYuuIH commented Jun 9, 2026

Copy link
Copy Markdown
Contributor

Summary

Update the GitHub App setup guide to match the current JupyterHub GitHub team synchronization flow. The documentation now explains both user-facing GitHub OAuth settings and the platform-owned GitHub App installation token settings used for team/group sync.

What Changed

  • Added the new hub.config.GitHubOAuthenticator settings:
    • app_id
    • installation_id (optional; can be auto-discovered from the org installation)
    • private_key_file / private_key
    • team_sync_ttl_seconds
  • Documented that the GitHub App must be installed on the same organization configured by custom.githubOrgName.
  • Documented the required organization permission: Members: Read-only.
  • Clarified that changing GitHub App permissions after installation requires org-owner approval on the installed app.
  • Added troubleshooting for Resource not accessible by integration, which indicates missing or unapproved GitHub App organization permissions.
  • Clarified that team mapping keys are normalized to GitHub team slugs for API lookup, while JupyterHub group names remain based on the configured keys.
  • Explained the current sync behavior: list actual org teams first, intersect with configured mappings, then batch team member lookups through GitHub GraphQL.

Validation

  • Ran make html successfully.
  • Sphinx reported two pre-existing warnings in unrelated installation documentation pages; this PR did not introduce new warnings in the GitHub App setup page.

Notes

This PR targets the docs branch only and does not change runtime code.

@MioYuuIH MioYuuIH marked this pull request as draft June 10, 2026 01:58
@MioYuuIH MioYuuIH marked this pull request as ready for review June 10, 2026 02:12
@KerwinTsaiii KerwinTsaiii merged commit 24c62b3 into docs Jun 11, 2026
2 checks passed
@MioYuuIH MioYuuIH deleted the docs-github-app-team-sync-config branch June 11, 2026 04:35
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants