Docs GitHub enhancements

README.md

@@ -47,7 +47,7 @@ source/
 │   ├── authentication-guide.md
 │   ├── user-management.md
 │   ├── quota-system.md
-│   └── github-oauth-setup.md
+│   └── github-app-setup.md
 ├── user-guide/                  # User guides
 │   ├── index.md
 │   └── admin-manual.md

source/conf.py

@@ -39,6 +39,7 @@
 
 html_theme = 'sphinx_book_theme'
 html_static_path = ['_static']
+html_favicon = "_static/images/favicon.ico"
 
 # MyST parser settings
 myst_enable_extensions = [

source/introduction/overview.md

@@ -29,7 +29,7 @@ The Hub currently supports four authentication modes:
 - `github`
 - `multi`
 
-`multi` combines GitHub OAuth and native local accounts on one login page. In GitHub-backed deployments, GitHub team membership can be synchronized into JupyterHub groups and used for resource access control.
+`multi` combines GitHub App and native local accounts on one login page. In GitHub-backed deployments, GitHub team membership can be synchronized into JupyterHub groups and used for resource access control.
 
 ### Admin Console
 

source/jupyterhub/README.md

@@ -6,7 +6,7 @@
 - [User Management Guide](./user-management.md) - Admin console and CLI-based user operations
 - [User Quota System](./quota-system.md) - Quota balances, rates, refresh rules, and admin actions
 - [Monitoring Deployment Guide](./monitoring.md) - Prometheus, Grafana, ServiceMonitor, dashboard, and alert setup
-- [GitHub App Setup](./github-oauth-setup.md) - Optional GitHub App integration for private repository access
+- [GitHub App Setup](./github-app-setup.md) - Optional GitHub App integration for private repository access
 - [Configuration Reference](./configuration-reference.md) - Detailed `runtime/values.yaml` and chart configuration
 
 ---
@@ -39,8 +39,8 @@ The current Hub supports four auth modes via `custom.authMode`:
 
 - `auto-login` - Automatically logs everyone in as a shared user for simple installs
 - `dummy` - Accepts any username/password for testing only
-- `github` - GitHub OAuth only
-- `multi` - GitHub OAuth plus native local accounts on a single login page
+- `github` - GitHub App only
+- `multi` - GitHub App plus native local accounts on a single login page
 
 In GitHub-backed modes, the Hub can also sync GitHub team membership into JupyterHub groups and use those groups for resource visibility.
 
@@ -194,7 +194,7 @@ custom:
       - bitbucket.org
 ```
 
-For GitHub App setup details, see [GitHub App Setup](./github-oauth-setup.md).
+For GitHub App setup details, see [GitHub App Setup](./github-app-setup.md).
 
 ### Verify Hub State After A Change
 
@@ -217,4 +217,4 @@ kubectl get cronjobs -n jupyterhub -l app.kubernetes.io/component=quota-refresh
 2. Then read [Authentication Guide](./authentication-guide.md)
 3. For operator tasks, use [User Management Guide](./user-management.md)
 4. For quota-enabled deployments, read [User Quota System](./quota-system.md)
-5. For private repository flows, read [GitHub App Setup](./github-oauth-setup.md)
+5. For private repository flows, read [GitHub App Setup](./github-app-setup.md)

source/jupyterhub/authentication-guide.md

@@ -12,8 +12,8 @@ Supported modes:
 |------|---------|
 | `auto-login` | Shared local mode with no credentials |
 | `dummy` | Testing mode that accepts any username/password |
-| `github` | GitHub OAuth only |
-| `multi` | GitHub OAuth plus native local accounts |
+| `github` | GitHub App only |
+| `multi` | GitHub App plus native local accounts |
 
 The current checked-in single-node defaults use `auto-login`.
 
@@ -33,14 +33,14 @@ The current checked-in single-node defaults use `auto-login`.
 
 ### `github`
 
-- only GitHub OAuth is offered
+- only GitHub App is offered
 - organization membership can be enforced through `allowed_organizations`
 - GitHub teams can be synchronized into Hub groups
 
 ### `multi`
 
 - a combined login page is shown
-- GitHub OAuth and local accounts both appear on the same page
+- GitHub App and local accounts both appear on the same page
 - local users are backed by the custom first-use authenticator
 
 ## Admin Bootstrap
@@ -65,9 +65,9 @@ kubectl -n jupyterhub get secret jupyterhub-admin-credentials \
   -o jsonpath='{.data.api-token}' | base64 -d && echo
 ```
 
-## GitHub OAuth
+## GitHub App
 
-GitHub OAuth configuration lives under `hub.config.GitHubOAuthenticator`.
+GitHub App configuration lives under `hub.config.GitHubOAuthenticator`.
 
 ```yaml
 custom:
@@ -118,7 +118,7 @@ custom:
 
 When configured, GitHub-authenticated users can install or authorize the app and use repo-picker flows on the spawn page.
 
-For setup instructions, see [GitHub App Setup](github-oauth-setup.md).
+For setup instructions, see [GitHub App Setup](github-app-setup.md).
 
 ## Native Accounts
 
@@ -256,6 +256,6 @@ This usually means the new password does not satisfy the current strength policy
 
 ## Related Documentation
 
-- [GitHub App Setup](github-oauth-setup.md)
+- [GitHub App Setup](github-app-setup.md)
 - [User Management Guide](user-management.md)
 - [Configuration Reference](configuration-reference.md)

source/jupyterhub/configuration-reference.md

@@ -40,8 +40,8 @@ Supported values:
 |------|---------|
 | `auto-login` | Shared no-credential local mode |
 | `dummy` | Testing-only any-user mode |
-| `github` | GitHub OAuth only |
-| `multi` | GitHub OAuth plus native accounts |
+| `github` | GitHub App only |
+| `multi` | GitHub App plus native accounts |
 
 ## 2. `custom.adminUser`
 
@@ -81,7 +81,7 @@ Key behavior:
 
 - `githubAppName` enables GitHub App install / repo picker flows for GitHub-authenticated users
 - `defaultAccessToken` provides a fallback private-repo token for all users
-- token priority is GitHub OAuth token first, then `defaultAccessToken`
+- token priority is GitHub App token first, then `defaultAccessToken`
 - a resource must also opt in with `metadata.allowGitClone: true`
 
 ## 5. `custom.accelerators`

source/jupyterhub/github-oauth-setup.md → source/jupyterhub/github-app-setup.md

@@ -2,6 +2,10 @@
 
 This guide will walk you through the process of setting up a GitHub App for your JupyterHub deployment.
 
+:::{note}
+This document assumes that you have setup `authMode` to either `github` or `multi` in your runtime yaml configuration file. See details [here](authentication-guide.md).
+:::
+
 ## Prerequisites
 
 1. A GitHub account
@@ -76,9 +80,12 @@ GitHub Apps are the recommended way to integrate with GitHub. They are created u
 :::
 
 1. Go to your organization's GitHub App creation page:
-   `https://github.com/organizations/<your-organization>/settings/apps/new`
+   - `https://github.com/organizations/<your-organization>/settings/apps/new`
+   - or in your Organization `https://github.com/<your-organization>/`, click the **Settings** tab, then in the left panel expand **Developer settings** and click *GitHub Apps*
+
+2. Click New **GitHub App**.
 
-2. Fill in the basic information:
+3. Fill in the basic information:
    - **GitHub App name**: A unique name (e.g., "auplc-hub")
    - **Homepage URL**: Your JupyterHub URL (e.g., `https://your.domain.com`)
    - **Callback URL**: Your OAuth callback URL
@@ -88,7 +95,7 @@ GitHub Apps are the recommended way to integrate with GitHub. They are created u
    - **Request user authorization (OAuth) during installation**: Check
    - **Webhook -> Active**: Uncheck (not needed)
 
-3. Set permissions:
+4. Set permissions:
    - **Repository permissions**:
       - `Contents`: Read-only (for cloning private repos)
       - `Metadata`: Read-only (selected by default)
@@ -99,23 +106,24 @@ GitHub Apps are the recommended way to integrate with GitHub. They are created u
    `Members: Read-only` is required for the Hub's platform-owned team synchronization. Without this organization permission, the Hub cannot list organization teams or team members and logs errors such as `Resource not accessible by integration` when calling the GitHub GraphQL API.
    :::
 
-4. Installation scope:
+5. Installation scope:
    - **Where can this GitHub App be installed?**: Any account
-   - Click **Create GitHub App**
 
-5. After creation, note down the following:
-    - **Client ID**: Displayed on the App's General page (e.g., `Iv23liXXXXXX`)
-    - **Client secret**: Click **Generate a new client secret** -- copy it immediately
+6. Click **Create GitHub App**
+
+7. After creation, note down the following:
     - **App ID**: Displayed on the App's General page. This is different from the Client ID.
-    - **App slug**: The URL-safe name in the App's URL (e.g., `auplc-hub`)
+    - **Client ID**: Displayed on the App's General page (e.g., `Iv23liXXXXXX`). This is different from the App ID.
+    - **Client secret**: Click **Generate a new client secret** -- copy it immediately
+    - **GitHub App name**: The URL-safe name in the App's URL (e.g., `auplc-hub`)
 
-6. Generate a private key:
+8. Generate a **Private key**:
    - On the App's General page, click **Generate a private key**.
    - Store the downloaded `.pem` file as a Kubernetes secret or mount it into the Hub pod by your deployment's secret-management process.
    - Record the mounted file path. You will use it as `hub.config.GitHubOAuthenticator.private_key_file`.
 
-7. Install the GitHub App on the organization:
-   - Open the App's **Install App** page.
+9. Install the GitHub App on the organization:
+   - In the left panel, Open the App's **Install App** page.
    - Install it on the same organization configured as `custom.githubOrgName`.
    - Select the repositories users may access if private repository cloning is enabled.
    - If you later add or change permissions, an organization owner must approve the updated installation permissions.
@@ -124,7 +132,7 @@ GitHub Apps are the recommended way to integrate with GitHub. They are created u
 
 ## Step 5: Configure JupyterHub
 
-1. Open your deployment configuration file (`runtime/values.yaml` or environment-specific override)
+1. Open your deployment configuration file (`runtime/values.yaml` or `values-multi-nodes.yaml` or environment-specific override)
 
 2. Add the GitHub App configuration:
 
@@ -223,7 +231,7 @@ If you are currently using a legacy GitHub OAuth App, follow these steps to migr
 
 ### Migration Steps
 
-1. **Create a GitHub App** under your organization (see Step 4 above)
+1. **Create a GitHub App** under your organization (see [Step 4](#step-4-create-a-github-app) above)
 
 2. **Update `values.yaml`** -- change the OAuth credentials and add GitHub App server-to-server settings:
 

source/jupyterhub/index.md

@@ -11,4 +11,4 @@ This section provides comprehensive guides for configuring and managing your Jup
 - {doc}`admin-manual` - Run common administrator workflows
 - {doc}`quota-system` - Configure quotas
 - {doc}`monitoring` - Connect Hub metrics to Prometheus and Grafana
-- {doc}`github-oauth-setup` - GitHub OAuth setup
+- {doc}`github-oauth-setup` - GitHub App setup

source/user-guide/index.md

@@ -17,7 +17,7 @@ Detailed end-user documentation may be expanded in future releases; contact your
 
 ### Common Tasks
 
-- **Login**: Use GitHub OAuth or native credentials
+- **Login**: Use GitHub App or native credentials
 - **Start Server**: Select your desired environment and resources
 - **Stop Server**: Always stop your server when finished to free up resources
 - **File Management**: Use the file browser in JupyterLab