Skip to content

Add 'Connect to Actions Job Debugger' command#583

Open
rentziass wants to merge 1 commit intodebuggerfrom
rentziass/debugger-connect-command
Open

Add 'Connect to Actions Job Debugger' command#583
rentziass wants to merge 1 commit intodebuggerfrom
rentziass/debugger-connect-command

Conversation

@rentziass
Copy link
Copy Markdown
Member

@rentziass rentziass commented Apr 9, 2026

This is the first step toward bringing the Actions job debugging experience into VS Code.

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).

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.

Copilot AI review requested due to automatic review settings April 9, 2026 15:10
@rentziass rentziass requested a review from a team as a code owner April 9, 2026 15:10
Copy link
Copy Markdown

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.connect activation 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 keep onDebugResolve for 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>
@rentziass rentziass force-pushed the rentziass/debugger-connect-command branch from d03e442 to 7f58e2c Compare April 9, 2026 15:23
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants