Add 'Connect to Actions Job Debugger' command#583
Open
Conversation
There was a problem hiding this comment.
Pull request overview
Adds an initial VS Code-side “connect” flow for the GitHub Actions Job Debugger MVP, enabling a DAP-over-WebSocket debug session to an Actions runner via a Dev Tunnel URL and GitHub authentication.
Changes:
- Adds a new command to prompt for a Dev Tunnel
wss://URL and start an attach debug session. - Implements an inline debug adapter that bridges DAP messages over WebSocket (with keepalive and early-event buffering).
- Adds tunnel URL validation + unit tests, and wires up debugger contributions/dependencies.
Show a summary per file
| File | Description |
|---|---|
| src/extension.ts | Registers the new debugger feature during extension activation. |
| src/debugger/debugger.ts | Implements the command + debug adapter factory/tracker and token handoff. |
| src/debugger/webSocketDapAdapter.ts | Adds a DAP-over-WebSocket inline adapter with keepalive and message patching/buffering. |
| src/debugger/tunnelUrl.ts | Validates tunnel URLs to restrict token exposure to approved domains/scheme. |
| src/debugger/tunnelUrl.test.ts | Adds unit tests for tunnel URL validation. |
| README.md | Documents the preview connect flow for the debugger. |
| package.json | Contributes the debugger type/command and adds ws dependencies/activation hook. |
| package-lock.json | Locks ws and @types/ws additions. |
Copilot's findings
Tip
Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comments suppressed due to low confidence (1)
package.json:32
- The new command is contributed in package.json but the extension isn’t activated on command execution. Without an
onCommand:github-actions.debugger.connectactivation event, users in workspaces that don’t match the existing activation events (e.g. empty workspace) may see the command but it won’t run because it isn’t registered yet. Add an onCommand activation event for this command (and keeponDebugResolvefor sessions started other ways).
"activationEvents": [
"onView:workflows",
"onView:settings",
"onDebugResolve:github-actions-job",
"workspaceContains:**/.github/workflows/**",
"workspaceContains:**/action.yml",
"workspaceContains:**/action.yaml"
],
- Files reviewed: 7/8 changed files
- Comments generated: 6
This is the first step toward bringing the Actions job debugging
experience into VS Code. The full vision is described in the ADR
(c2c-actions/docs/adrs/9758-actions-job-debugger-mvp.md): users will be
able to re-run a job with a debugger attached and connect their editor
to inspect variables, evaluate expressions, and run commands in the
job's runtime context — all through the standard Debug Adapter Protocol.
This PR adds the extension-side connect flow:
- A new command ('GitHub Actions: Connect to Actions Job Debugger...')
that prompts for a Dev Tunnel wss:// URL and starts a debug session.
- A WebSocket-based inline debug adapter (DebugAdapterInlineImplementation)
that speaks DAP-over-WebSocket directly to the runner — no local TCP
bridge needed.
- Authentication using the existing VS Code GitHub session token, sent
as a Bearer token on the WebSocket handshake.
The tunnel URL is entered manually for now. Once the server-side
endpoint that serves the debugger URL for a job is deployed, we can
automate this (and eventually add 're-run with debugger' directly from
the extension).
Security hardening:
- Tunnel URLs restricted to wss://*.devtunnels.ms only.
- Auth tokens kept in extension-private memory with cryptographic
nonces, never exposed through DebugConfiguration.
- Tunnel URL re-validated in the adapter factory (defense in depth).
- 30s connection timeout prevents indefinite hangs.
- WebSocket send/ping errors trigger clean session teardown.
- Debugger registration gated to Desktop VS Code (Node context).
Workarounds for VS Code quirks (to be removed as the runner evolves):
- Synthetic source references on stack frames so VS Code auto-focuses
the top frame and loads variables on connect/step.
- Buffering of early 'stopped' events that the runner sends before
VS Code completes the DAP handshake.
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
d03e442 to
7f58e2c
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
This is the first step toward bringing the Actions job debugging experience into VS Code.
This PR adds the extension-side connect flow:
The tunnel URL is entered manually for now. Once the server-side
endpoint that serves the debugger URL for a job is deployed, we can
automate this (and eventually add 're-run with debugger' directly from
the extension).
Workarounds for VS Code quirks (to be removed as the runner evolves):