From 7da4fb414090b731773e8dd28c7d11f48dd1a1f7 Mon Sep 17 00:00:00 2001 From: Anatolii Bazko Date: Wed, 22 Jul 2026 15:20:25 +0000 Subject: [PATCH 1/3] procedures: add Device Auth Tokens documentation Add a new procedure article for connecting to GitHub using device authorization from the Dashboard's User Preferences page. Update the GitHub OAuth App setup procedure to include enabling Device Flow. Signed-off-by: che-ai-assistant Signed-off-by: Anatolii Bazko --- .../proc_setting-up-the-github-oauth-app.adoc | 4 ++ modules/end-user-guide/nav.adoc | 1 + ...-to-github-using-device-authorization.adoc | 61 +++++++++++++++++++ 3 files changed, 66 insertions(+) create mode 100644 modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc diff --git a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc index 9c5bd0204b..951536e953 100644 --- a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc +++ b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc @@ -32,6 +32,10 @@ Set up a GitHub OAuth App using OAuth 2.0. . Copy and save the *GitHub OAuth Client Secret* for use when applying the GitHub OAuth App Secret. +. To enable the device authorization flow for the Dashboard, scroll to *Enable Device Flow* and select the checkbox, then click *Update application*. ++ +NOTE: This step is required if you want users to connect their GitHub accounts from the {prod-short} Dashboard using *User Preferences > Device Auth Tokens*. + .Additional resources * link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub Docs: Creating an OAuth App] diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index 28bc8bf1b6..d504e2a790 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -36,6 +36,7 @@ * xref:using-ai-assistants-in-workspaces.adoc[] ** xref:configuring-an-ai-provider-api-key.adoc[] ** xref:changing-the-ai-tool-on-a-workspace.adoc[] +* xref:connecting-to-github-using-device-authorization.adoc[] * xref:using-credentials-and-configurations-in-workspaces.adoc[] ** xref:mounting-secrets.adoc[] *** xref:creating-image-pull-secrets.adoc[] diff --git a/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc new file mode 100644 index 0000000000..0f447ba9e6 --- /dev/null +++ b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc @@ -0,0 +1,61 @@ +:_content-type: PROCEDURE +:description: Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. +:keywords: user-guide, github, device-authorization, device-auth, token, oauth +:navtitle: Connecting to GitHub using device authorization +:page-aliases: + +[id="connecting-to-github-using-device-authorization"] += Connect to GitHub using device authorization + +[role="_abstract"] +Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. Device authentication tokens are GitHub OAuth tokens stored as {kubernetes} Secrets. They enable Git operations in your workspaces without requiring a personal access token. + +.Prerequisites + +* Your administrator has xref:administration-guide:configuring-oauth-2-for-github.adoc[configured GitHub OAuth] with Device Flow enabled. + +.Procedure + +. In the {prod-short} dashboard, go to *User Preferences > Device Auth Tokens*. + +. Click *Connect to GitHub*. ++ +A modal opens displaying a one-time code. + +. Click the copy button next to the code to copy it to your clipboard. + +. Click the link:https://github.com/login/device[github.com/login/device] link to open the GitHub device activation page. + +. Paste the one-time code on the GitHub page and click *Continue*. + +. Authorize the application when prompted by GitHub. ++ +After successful authorization, the modal closes and the new token appears in the *Device Auth Tokens* table. + +.Verification + +* Verify that the new token is listed in the *Device Auth Tokens* table with a valid status. + +[id="deleting-device-auth-tokens"] +== Deleting device auth tokens + +Deleting a device auth token removes the {kubernetes} Secret and revokes the GitHub authorization. + +.Procedure + +* To delete a single token: + +.. Click the actions menu (*⋮*) on the token row. +.. Click *Delete*. +.. Select the confirmation checkbox and click *Delete*. + +* To delete multiple tokens: + +.. Select the checkboxes next to the tokens you want to delete. +.. Click *Delete* in the toolbar. +.. Select the confirmation checkbox and click *Delete*. + +.Additional resources + +* xref:administration-guide:configuring-oauth-2-for-github.adoc[] +* xref:get-started:using-a-git-provider-access-token.adoc[] From 94d059ab68cd551db83c3af7a76c199608b71814 Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Wed, 22 Jul 2026 18:53:22 +0300 Subject: [PATCH 2/3] docs: address PR review feedback on device auth tokens - Page title: use gerund form ("Connecting to GitHub..." matches other titles) - nav.adoc: move article under mounting-secrets alongside PAT article (both cover Git credential mechanisms backed by K8s Secrets) - Remove redundant trailing "link" word from link macro - Prerequisite: clarify it requires a GitHub OAuth App (not GitHub App) with Device Flow enabled - Admin guide: split combined "Enable Device Flow + click Update" step into two distinct steps for consistency with other procedure steps - Additional resources: add lead-in phrase to PAT xref to clarify it is an alternative authentication mechanism Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../partials/proc_setting-up-the-github-oauth-app.adoc | 4 +++- modules/end-user-guide/nav.adoc | 2 +- .../connecting-to-github-using-device-authorization.adoc | 8 ++++---- 3 files changed, 8 insertions(+), 6 deletions(-) diff --git a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc index 951536e953..d47fcf9a81 100644 --- a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc +++ b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc @@ -32,10 +32,12 @@ Set up a GitHub OAuth App using OAuth 2.0. . Copy and save the *GitHub OAuth Client Secret* for use when applying the GitHub OAuth App Secret. -. To enable the device authorization flow for the Dashboard, scroll to *Enable Device Flow* and select the checkbox, then click *Update application*. +. Scroll to the *Device flow* section and select the *Enable Device Flow* checkbox. + NOTE: This step is required if you want users to connect their GitHub accounts from the {prod-short} Dashboard using *User Preferences > Device Auth Tokens*. +. Click *Update application*. + .Additional resources * link:https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app[GitHub Docs: Creating an OAuth App] diff --git a/modules/end-user-guide/nav.adoc b/modules/end-user-guide/nav.adoc index d504e2a790..168ab7cd1f 100644 --- a/modules/end-user-guide/nav.adoc +++ b/modules/end-user-guide/nav.adoc @@ -36,11 +36,11 @@ * xref:using-ai-assistants-in-workspaces.adoc[] ** xref:configuring-an-ai-provider-api-key.adoc[] ** xref:changing-the-ai-tool-on-a-workspace.adoc[] -* xref:connecting-to-github-using-device-authorization.adoc[] * xref:using-credentials-and-configurations-in-workspaces.adoc[] ** xref:mounting-secrets.adoc[] *** xref:creating-image-pull-secrets.adoc[] *** xref:get-started-user:using-a-git-provider-access-token.adoc[] +*** xref:connecting-to-github-using-device-authorization.adoc[] ** xref:mounting-configmaps.adoc[] *** xref:mounting-git-configuration.adoc[] *** xref:mounting-ssh-configuration.adoc[] diff --git a/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc index 0f447ba9e6..8548ed8974 100644 --- a/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc +++ b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc @@ -5,14 +5,14 @@ :page-aliases: [id="connecting-to-github-using-device-authorization"] -= Connect to GitHub using device authorization += Connecting to GitHub using device authorization [role="_abstract"] Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. Device authentication tokens are GitHub OAuth tokens stored as {kubernetes} Secrets. They enable Git operations in your workspaces without requiring a personal access token. .Prerequisites -* Your administrator has xref:administration-guide:configuring-oauth-2-for-github.adoc[configured GitHub OAuth] with Device Flow enabled. +* Your administrator has configured a GitHub OAuth App with Device Flow enabled as described in xref:administration-guide:configuring-oauth-2-for-github.adoc[Configuring OAuth 2.0 for GitHub]. .Procedure @@ -24,7 +24,7 @@ A modal opens displaying a one-time code. . Click the copy button next to the code to copy it to your clipboard. -. Click the link:https://github.com/login/device[github.com/login/device] link to open the GitHub device activation page. +. Click link:https://github.com/login/device[github.com/login/device] to open the GitHub device activation page. . Paste the one-time code on the GitHub page and click *Continue*. @@ -58,4 +58,4 @@ Deleting a device auth token removes the {kubernetes} Secret and revokes the Git .Additional resources * xref:administration-guide:configuring-oauth-2-for-github.adoc[] -* xref:get-started:using-a-git-provider-access-token.adoc[] +* For an alternative Git authentication method, see xref:get-started:using-a-git-provider-access-token.adoc[]. From 2d04f2fd34f84c1745e488edd14c46bcc1f49d3c Mon Sep 17 00:00:00 2001 From: Oleksii Orel Date: Tue, 28 Jul 2026 14:43:59 +0300 Subject: [PATCH 3/3] docs: address second-round PR review feedback on device auth tokens - Remove empty :page-aliases: attribute - Fix abstract: "Device authentication tokens" -> "Device Auth Tokens" - Add note clarifying OAuth App vs GitHub App requirement - Add GHES hostname note on the device activation URL step - Add note about admin-controlled OAuth scopes on authorization step - Add token lifecycle info: tokens do not expire automatically - Restructure deletion procedure to use ordered list markers - Add verification step to the deletion subsection - Add troubleshooting section for expired one-time codes - Mark Device Flow setup step as optional; add xref to user docs - Add note in OAuth assembly for admins with existing OAuth App setup - Fix xref module: get-started -> get-started-user (post-rebase) Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel --- .../pages/configuring-oauth-2-for-github.adoc | 5 ++++ .../proc_setting-up-the-github-oauth-app.adoc | 6 ++-- ...-to-github-using-device-authorization.adoc | 28 +++++++++++++------ 3 files changed, 28 insertions(+), 11 deletions(-) diff --git a/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc b/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc index ed1587a8fb..e1d1dafccb 100644 --- a/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc +++ b/modules/administration-guide/pages/configuring-oauth-2-for-github.adoc @@ -12,6 +12,11 @@ To enable users to work with a remote Git repository that is hosted on GitHub: . Set up a link:https://docs.github.com/en/apps/creating-github-apps/about-creating-github-apps/about-creating-github-apps#about-github-apps[GitHub App] or a link:https://docs.github.com/en/apps/oauth-apps/using-oauth-apps[OAuth App]. . Apply the GitHub App or OAuth App Secret. +[NOTE] +==== +If you previously configured a GitHub OAuth App and want to enable Device Auth Tokens for users, also enable Device Flow as described in <>. +==== + include::partial$proc_setting-up-the-github-oauth-app.adoc[leveloffset=+1] include::partial$proc_setting-up-the-github-app.adoc[leveloffset=+1] diff --git a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc index d47fcf9a81..ef7d28423c 100644 --- a/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc +++ b/modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adoc @@ -32,11 +32,11 @@ Set up a GitHub OAuth App using OAuth 2.0. . Copy and save the *GitHub OAuth Client Secret* for use when applying the GitHub OAuth App Secret. -. Scroll to the *Device flow* section and select the *Enable Device Flow* checkbox. +. *(Optional)* Scroll to the *Device flow* section and select the *Enable Device Flow* checkbox. + -NOTE: This step is required if you want users to connect their GitHub accounts from the {prod-short} Dashboard using *User Preferences > Device Auth Tokens*. +NOTE: Enable this option to allow users to connect their GitHub accounts from the {prod-short} Dashboard using *User Preferences > Device Auth Tokens*. See xref:end-user-guide:connecting-to-github-using-device-authorization.adoc[]. -. Click *Update application*. +. If you selected *Enable Device Flow*, click *Update application*. .Additional resources diff --git a/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc index 8548ed8974..6cbd6b4f98 100644 --- a/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc +++ b/modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adoc @@ -2,17 +2,18 @@ :description: Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. :keywords: user-guide, github, device-authorization, device-auth, token, oauth :navtitle: Connecting to GitHub using device authorization -:page-aliases: [id="connecting-to-github-using-device-authorization"] = Connecting to GitHub using device authorization [role="_abstract"] -Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. Device authentication tokens are GitHub OAuth tokens stored as {kubernetes} Secrets. They enable Git operations in your workspaces without requiring a personal access token. +Connect your GitHub account to {prod-short} using the device authorization flow directly from the Dashboard. Device Auth Tokens are GitHub OAuth tokens stored as {kubernetes} Secrets. They enable Git operations in your workspaces without requiring a personal access token. .Prerequisites * Your administrator has configured a GitHub OAuth App with Device Flow enabled as described in xref:administration-guide:configuring-oauth-2-for-github.adoc[Configuring OAuth 2.0 for GitHub]. ++ +NOTE: This feature requires the GitHub OAuth App configuration. It is not available when GitHub authentication is configured using a GitHub App. .Procedure @@ -25,11 +26,15 @@ A modal opens displaying a one-time code. . Click the copy button next to the code to copy it to your clipboard. . Click link:https://github.com/login/device[github.com/login/device] to open the GitHub device activation page. ++ +NOTE: For GitHub Enterprise Server, replace `github.com` with your instance hostname. . Paste the one-time code on the GitHub page and click *Continue*. . Authorize the application when prompted by GitHub. + +NOTE: The permissions granted are determined by the OAuth App configuration set by your administrator. ++ After successful authorization, the modal closes and the new token appears in the *Device Auth Tokens* table. .Verification @@ -39,23 +44,30 @@ After successful authorization, the modal closes and the new token appears in th [id="deleting-device-auth-tokens"] == Deleting device auth tokens -Deleting a device auth token removes the {kubernetes} Secret and revokes the GitHub authorization. +Deleting a device auth token removes the {kubernetes} Secret and revokes the GitHub authorization. Device Auth Tokens do not expire automatically. To disconnect your GitHub account, delete the token from this page or revoke access from your GitHub account settings. .Procedure -* To delete a single token: - +. To delete a single token: .. Click the actions menu (*⋮*) on the token row. .. Click *Delete*. .. Select the confirmation checkbox and click *Delete*. -* To delete multiple tokens: - +. To delete multiple tokens: .. Select the checkboxes next to the tokens you want to delete. .. Click *Delete* in the toolbar. .. Select the confirmation checkbox and click *Delete*. +.Verification + +* Verify that the deleted token no longer appears in the *Device Auth Tokens* table. + +[id="troubleshooting-device-auth-tokens"] +== Troubleshooting + +If the one-time code expires before you complete the authorization on GitHub (codes expire after approximately 15 minutes), close the modal and click *Connect to GitHub* again to start a new device authorization flow. + .Additional resources * xref:administration-guide:configuring-oauth-2-for-github.adoc[] -* For an alternative Git authentication method, see xref:get-started:using-a-git-provider-access-token.adoc[]. +* For an alternative Git authentication method, see xref:get-started-user:using-a-git-provider-access-token.adoc[].