diff --git a/README.md b/README.md index daca7028..20bb6819 100644 --- a/README.md +++ b/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 diff --git a/source/_static/images/favicon.ico b/source/_static/images/favicon.ico new file mode 100644 index 00000000..3f148e32 Binary files /dev/null and b/source/_static/images/favicon.ico differ diff --git a/source/_static/images/github-1.png b/source/_static/images/github-1.png index 9b96388b..efe5f4a4 100644 Binary files a/source/_static/images/github-1.png and b/source/_static/images/github-1.png differ diff --git a/source/_static/images/github-4.png b/source/_static/images/github-4.png index 1c367d53..705375c7 100644 Binary files a/source/_static/images/github-4.png and b/source/_static/images/github-4.png differ diff --git a/source/conf.py b/source/conf.py index ed8dd337..09baba8b 100644 --- a/source/conf.py +++ b/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 = [ diff --git a/source/introduction/overview.md b/source/introduction/overview.md index 2c04625a..f2f1ef12 100644 --- a/source/introduction/overview.md +++ b/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 diff --git a/source/jupyterhub/README.md b/source/jupyterhub/README.md index 4f7e592b..92f139ad 100644 --- a/source/jupyterhub/README.md +++ b/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) diff --git a/source/jupyterhub/authentication-guide.md b/source/jupyterhub/authentication-guide.md index 0ec60b6f..f6c3bac7 100644 --- a/source/jupyterhub/authentication-guide.md +++ b/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) diff --git a/source/jupyterhub/configuration-reference.md b/source/jupyterhub/configuration-reference.md index 0aa65d44..38ce37b7 100644 --- a/source/jupyterhub/configuration-reference.md +++ b/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` diff --git a/source/jupyterhub/github-oauth-setup.md b/source/jupyterhub/github-app-setup.md similarity index 91% rename from source/jupyterhub/github-oauth-setup.md rename to source/jupyterhub/github-app-setup.md index 155d214c..1ea349ec 100644 --- a/source/jupyterhub/github-oauth-setup.md +++ b/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//settings/apps/new` + - `https://github.com/organizations//settings/apps/new` + - or in your Organization `https://github.com//`, 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: diff --git a/source/jupyterhub/index.md b/source/jupyterhub/index.md index cfcf0f9b..84d5653b 100644 --- a/source/jupyterhub/index.md +++ b/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 diff --git a/source/user-guide/index.md b/source/user-guide/index.md index a03b7330..1a7c6d8e 100644 --- a/source/user-guide/index.md +++ b/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