[docs] condense verbose sections in common-issues.md#24010
Conversation
Remove repetitive code blocks in the debug logging section by combining five separate bash examples into a single annotated block. Simplify the Copilot license diagnosis steps and the timeout explanation. Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
There was a problem hiding this comment.
Pull request overview
This PR reduces verbosity in common-issues.md by consolidating several troubleshooting sections while aiming to preserve the original technical guidance.
Changes:
- Condenses “Copilot License or Inference Access Issues” diagnosis steps into a single local test snippet.
- Simplifies the “Workflow Job Timed Out” guidance by removing an intermediate hint block and tightening the prose.
- Replaces multiple DEBUG examples with one annotated block and shortens the explanation of log output fields.
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| ``` | ||
|
|
||
| If no `timeout-minutes` value is set in your workflow frontmatter, the default is 20 minutes. To increase the limit: | ||
| When a workflow job exceeds its time limit, GitHub Actions marks the run as `timed_out`. The default is 20 minutes. Increase it with: |
There was a problem hiding this comment.
The sentence "The default is 20 minutes" is ambiguous and can read as the GitHub Actions platform default (which is different). Consider clarifying that this is the gh-aw / workflow frontmatter default for the agent execution job (and that other/custom jobs may use the GitHub Actions default unless explicitly set).
| When a workflow job exceeds its time limit, GitHub Actions marks the run as `timed_out`. The default is 20 minutes. Increase it with: | |
| When a workflow job exceeds its time limit, GitHub Actions marks the run as `timed_out`. For gh-aw–compiled workflows, the default timeout for the agent execution job (set in the workflow frontmatter) is 20 minutes; other or custom jobs use the GitHub Actions default unless you set `timeout-minutes` explicitly. Increase it with: |
| - **Time elapsed** – time since the previous log entry (e.g., `+125ms`), which helps identify slow steps | ||
|
|
||
| Log namespaces follow a `pkg:filename` convention. Common namespaces include `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, and `parser:frontmatter`. Wildcards (`*`) match any suffix, so `workflow:*` captures all workflow-package logs. | ||
| Debug output goes to `stderr`. Each log line shows the namespace (`workflow:compiler`), message, and time elapsed since the previous entry. Common namespaces: `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, `parser:frontmatter`. Wildcards match any suffix (`workflow:*`). |
There was a problem hiding this comment.
"time elapsed since the previous entry" is slightly misleading: the logger implementation tracks the delta per namespace/logger instance (time since the previous log from that namespace), not necessarily since the previous log line overall. Consider tweaking the wording to avoid implying a global delta.
| Debug output goes to `stderr`. Each log line shows the namespace (`workflow:compiler`), message, and time elapsed since the previous entry. Common namespaces: `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, `parser:frontmatter`. Wildcards match any suffix (`workflow:*`). | |
| Debug output goes to `stderr`. Each log line shows the namespace (`workflow:compiler`), message, and time elapsed since the previous log from that namespace (not necessarily the previous log line overall). Common namespaces: `cli:compile_command`, `workflow:compiler`, `workflow:expression_extraction`, `parser:frontmatter`. Wildcards match any suffix (`workflow:*`). |
| ``` | ||
|
|
||
| If this command fails, the account associated with the token does not have a valid Copilot license or inference access. Contact your organization administrator to verify that the token owner has an active Copilot subscription with inference enabled. | ||
| If this fails, the token owner lacks a valid Copilot license or inference access. Contact your organization administrator to enable it. |
There was a problem hiding this comment.
"Contact your organization administrator to enable it" is ambiguous (what exactly needs enabling: a Copilot seat/license assignment, policy allowance, or inference access). Consider naming the specific action(s) the admin should take so readers know what to ask for.
| If this fails, the token owner lacks a valid Copilot license or inference access. Contact your organization administrator to enable it. | |
| If this fails, the token owner lacks a valid Copilot license or inference access. Contact your organization administrator to assign a GitHub Copilot license to the token owner and enable Copilot inference access for your organization. |
Reduces documentation bloat in
docs/src/content/docs/troubleshooting/common-issues.mdby condensing three verbose sections.Changes made
Enable Debug Logging (main reduction): Replaced 6 separate code blocks (each showing one variation of the
DEBUGenv var) with a single annotated block that covers all cases in fewer lines. Removed the bullet-point breakdown of log line fields — the information is preserved in the following prose sentence.Copilot License Diagnosis: Replaced a numbered 3-step list with a single inline snippet. All technical content is preserved.
Workflow Job Timed Out: Removed a redundant intermediate code block (showing
timeout-minutes: 30as a hint) since the section already shows the actual fix immediately after. Tightened closing sentence.Metrics
Issues
Screenshots could not be captured — Playwright container could not reach the agent container's bridge IP (
net::ERR_CONNECTION_TIMED_OUT). Page content was verified viacurlinstead; the rendered HTML confirms all condensed content is present and correctly formatted.References: §23882486166