procedures: Document GitHub Copilot Chat usage#3097
Conversation
Signed-off-by: Roman Nikitenko <rnikiten@redhat.com> Assisted-by: Cursor AI
|
Click here to review and test in web IDE: |
-525C86?logo=eclipse-che&labelColor=red){kind=icon}
|
🎊 Navigate the preview: https://6a05d228a307149b09738328--eclipse-che-docs-pr.netlify.app 🎊 |
RomanNikitenko
requested review from
a team,
deerskindoll,
gtrivedi88 and
mkuznyetsov
as code owners
Signed-off-by: Roman Nikitenko <rnikiten@redhat.com> Assisted-by: Cursor AI
| @@ -0,0 +1,88 @@ | |||
| :_content-type: PROCEDURE | |||
| :description: Using GitHub Copilot Chat in a Che workspace | |||
There was a problem hiding this comment.
CQA P8 — Gerund in description metadata
Update to match the imperative title.
| :description: Using GitHub Copilot Chat in a Che workspace | |
| :description: Set up GitHub Copilot Chat in a Che workspace |
| :_content-type: PROCEDURE | ||
| :description: Using GitHub Copilot Chat in a Che workspace | ||
| :keywords: copilot, github-copilot, copilot-chat, ai, extensions | ||
| :navtitle: Using GitHub Copilot Chat |
There was a problem hiding this comment.
CQA P8, Q3 — Gerund navtitle → imperative
Procedure titles must use an imperative verb, not a gerund.
| :navtitle: Using GitHub Copilot Chat | |
| :navtitle: Set up GitHub Copilot Chat |
| :navtitle: Using GitHub Copilot Chat | ||
|
|
||
| [id="using-github-copilot-chat"] | ||
| = Using GitHub Copilot Chat |
There was a problem hiding this comment.
CQA P8, Q3 — Gerund title → imperative
CQA 2.1 requires procedure titles to start with an imperative verb. "Using" is a gerund. Since this procedure covers both installation and authentication, "Set up" captures the scope.
| = Using GitHub Copilot Chat | |
| = Set up GitHub Copilot Chat |
| [id="using-github-copilot-chat"] | ||
| = Using GitHub Copilot Chat | ||
|
|
||
| You can use link:https://github.com/features/copilot[GitHub Copilot Chat] in a {prod-short} workspace with the Code - OSS editor by installing the link:https://open-vsx.org/extension/redhat/devspaces-copilot-chat-integration/0.36.2[Dev Spaces Copilot Chat Integration] extension (version 0.36.2) and authenticating with your GitHub account. |
There was a problem hiding this comment.
JTBD — WHY-first abstract
JTBD pattern requires leading with the user's goal (WHY), then the action (HOW). Current text starts with "You can use..." (HOW-first).
| You can use link:https://github.com/features/copilot[GitHub Copilot Chat] in a {prod-short} workspace with the Code - OSS editor by installing the link:https://open-vsx.org/extension/redhat/devspaces-copilot-chat-integration/0.36.2[Dev Spaces Copilot Chat Integration] extension (version 0.36.2) and authenticating with your GitHub account. | |
| To get AI-assisted coding suggestions in your {prod-short} workspace, install the link:https://open-vsx.org/extension/redhat/devspaces-copilot-chat-integration/0.36.2[Dev Spaces Copilot Chat Integration] extension (version 0.36.2) and authenticate with your GitHub account. |
Also consider defining an attribute for the version (see comment on line 41).
|
|
||
| * A GitHub account with an active link:https://github.com/features/copilot[GitHub Copilot] subscription. | ||
| * A running {prod-short} workspace with the Code - OSS editor. | ||
| * The following URLs must be accessible from the workspace (ensure they are whitelisted if you are in a restricted or air-gapped environment): |
There was a problem hiding this comment.
Conscious language violation — "whitelisted"
Per Red Hat Conscious Language policy, "whitelist/whitelisted" must not be used. Replace with "allowlisted" or restructure.
| * The following URLs must be accessible from the workspace (ensure they are whitelisted if you are in a restricted or air-gapped environment): | |
| * The following URLs must be accessible from the workspace (ensure they are added to the allowlist if you are in a restricted or air-gapped environment): |
| [IMPORTANT] | ||
| ==== | ||
| You must complete Device Authentication *before* attempting to use AI features. Initiating "Sign in to use AI Features" without a valid device authentication token causes authentication errors that require signing out and re-authenticating. | ||
| ==== |
There was a problem hiding this comment.
CQA Q11 — Admonition density
Two [IMPORTANT] blocks in a 4-step procedure is high density. This is critical sequencing information that belongs in the step narrative, not a separate admonition. Consider folding it into the step 2 text:
| [IMPORTANT] | |
| ==== | |
| You must complete Device Authentication *before* attempting to use AI features. Initiating "Sign in to use AI Features" without a valid device authentication token causes authentication errors that require signing out and re-authenticating. | |
| ==== | |
| IMPORTANT: You must complete Device Authentication *before* attempting to use AI features. Initiating "Sign in to use AI Features" without a valid device authentication token causes authentication errors that require signing out and re-authenticating. |
Alternatively, merge steps 2 and 3 into a single step with this warning inline, since they are part of the same authentication flow.
|
|
||
| .Verification | ||
|
|
||
| * The Copilot Chat panel opens and responds to prompts. |
There was a problem hiding this comment.
CQA Q14 — Thin verification
Make the verification actionable with a concrete check.
| * The Copilot Chat panel opens and responds to prompts. | |
| * Open the Copilot Chat panel, type a prompt such as "Explain this file", and verify that a response appears. |
| Device Authentication is a one-time step. The credentials are saved as a Kubernetes object and persist across workspaces on the same cluster. | ||
| ==== | ||
|
|
||
| .Troubleshooting |
There was a problem hiding this comment.
Modularity note — Embedded troubleshooting
For downstream backport, this troubleshooting section should be extracted to a separate module (ref_troubleshooting-github-copilot-chat.adoc or similar). For upstream che-docs, embedding is acceptable, but worth keeping in mind for the downstream sync.
| * Copilot Chat appears to be connected but does not respond to prompts. | ||
| * The Copilot Chat output log contains errors such as: | ||
| + | ||
| ---- |
There was a problem hiding this comment.
CQA Q18 — Listing block missing source annotation
Add a source annotation for consistency with CQA code block conventions.
| ---- | |
| [source,text] | |
| ---- |
| * xref:devfile-introduction.adoc[] | ||
| * xref:ides-in-workspaces.adoc[] | ||
| ** xref:microsoft-visual-studio-code-open-source-ide.adoc[] | ||
| ** xref:using-github-copilot-chat.adoc[] |
There was a problem hiding this comment.
Nav structure — Should be nested under VS Code page
GitHub Copilot Chat is specific to the Code-OSS editor. At ** level it appears as a sibling to all IDE pages, implying it applies to all IDEs. Nest it one level deeper under the VS Code page:
| ** xref:using-github-copilot-chat.adoc[] | |
| *** xref:using-github-copilot-chat.adoc[] |
2 participants
What does this pull request change?
Adds instructions how to authenticate
GitHub Copilot ChatusingDevice AuthenticationflowClick here to see screenshots
What issues does this pull request fix or reference?
eclipse-che/che#23536 (comment)
Specify the version of the product this pull request applies to
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.Assisted-by: Cursor AI