procedures: add Device Auth Tokens documentation - #3168
Conversation
|
Click here to review and test in web IDE: |
-525C86?logo=eclipse-che&labelColor=red){kind=icon}
|
🎊 Navigate the preview: https://6a7f0e189df0b22221ae60ed--eclipse-che-docs-pr.netlify.app 🎊 |
olexii4
left a comment
olexii4
left a comment
There was a problem hiding this comment.
G1. PR checklist items unchecked
All four checklist items remain unchecked. Vale validation can be run independently of the dashboard feature (che-dashboard#1633), which is still open. Worth confirming Vale is clean before merge.
G2. Deletion subsection discoverability
The == Deleting device auth tokens subsection (anchor #deleting-device-auth-tokens) has no nav entry - it is only reachable by scrolling to the bottom of the connect page. Users searching for "delete device auth token" may not find it through navigation. Consider whether a nav sub-entry pointing to the anchor would help, or whether keeping it on the same page is sufficient.
G3. No troubleshooting for known error scenarios
The dashboard handles five distinct error states during the device flow: device_flow_disabled, expired_token, access_denied, slow_down, and generic GitHub API errors. The device_flow_disabled error produces a specific message directing users to contact their admin. At minimum, a troubleshooting note for the expired_token case (codes typically expire after 15 minutes) would help users know to retry rather than report a bug.
G4. Token lifecycle not documented
The article covers creation and deletion but not: whether tokens expire, whether they are refreshed automatically, or what happens to running workspaces when a token is deleted or the GitHub authorization is revoked from the GitHub side. These are operational questions users will encounter in production.
olexii4
left a comment
olexii4
left a comment
There was a problem hiding this comment.
Second-round findings, additive to olexii4's review. Items addressed by the second commit (title form, nav placement, link redundancy, step splitting, additional resources context) are not repeated. The inline comments below cover new findings.
G5. Existing installations: new admin step is not surfaced at assembly level
The Device Flow steps are appended at the end of the initial-setup procedure. An administrator who already configured the GitHub OAuth App will not revisit that procedure to discover the new step. The parent assembly page configuring-oauth-2-for-github.adoc has no note calling out this new option. Consider adding a brief note at the assembly level - for example: "If you previously configured a GitHub OAuth App and want to enable Device Auth Tokens for your users, enable Device Flow as described in the setup procedure."
0a1bc7c to
2d04f2f
Compare
2d04f2f to
c9927eb
Compare
|
@olexii4 please check PR checks |
Documents the Device Auth Tokens tab in User Preferences introduced in eclipse-che/che-dashboard#1633. New article (connecting-to-github-using-device-authorization.adoc): - Connect to GitHub using the device authorization flow (RFC 8628) - Reconnect to replace a revoked or expired token in-place - Delete a single token or multiple tokens in bulk - Troubleshooting for expired one-time codes Updated admin procedure (proc_setting-up-the-github-oauth-app.adoc): - Optional steps to enable Device Flow on the GitHub OAuth App - Step to create the device-auth-config ConfigMap that enables the Connect to GitHub button in the Dashboard Updated assembly (configuring-oauth-2-for-github.adoc): - NOTE for admins who already configured the OAuth App and want to enable Device Auth Tokens without repeating the full setup Navigation: added the new article under Using credentials and configurations in workspaces > Mounting secrets. Assisted-by: Claude Sonnet 4.6 Signed-off-by: Oleksii Orel <oorel@redhat.com>
c9927eb to
ede3e33
Compare
3 participants
What does this pull request change?
Adds documentation for the new Device Auth Tokens tab in User Preferences, introduced in eclipse-che/che-dashboard#1633.
New article:
modules/end-user-guide/pages/connecting-to-github-using-device-authorization.adocUpdated article:
modules/administration-guide/partials/proc_setting-up-the-github-oauth-app.adocdevice-auth-configConfigMap in the {prod-short} namespace, which enables the Connect to GitHub button in the DashboardUpdated assembly:
modules/administration-guide/pages/configuring-oauth-2-for-github.adocNavigation: Updated
modules/end-user-guide/nav.adocto include the new article under Using credentials and configurations in workspaces > Mounting secrets.What issues does this pull request fix or reference?
Specify the version of the product this pull request applies to
next
Pull Request checklist
The author and the reviewers validate the content of this pull request with the following checklist, in addition to the automated tests.
Validate language on files added or modifiedstep reports no vale warnings.