Add Docker security flags for Playwright MCP Chromium compatibility

Copilot · pelikhan · Copilot · commit 875dbb7a542a · 2026-02-17T00:31:23.000Z
Co-authored-by: pelikhan &lt;4175913+pelikhan@users.noreply.github.com&gt;
diff --git a/docs/src/content/docs/reference/tools.md b/docs/src/content/docs/reference/tools.md
@@ -175,6 +175,8 @@ tools:
 
 **Domain Access**: Uses `network:` ecosystem bundles (`defaults`, `github`, `node`, `python`, etc.). Defaults to `["localhost", "127.0.0.1"]`. Domains auto-include subdomains.
 
+**GitHub Actions Compatibility**: Playwright runs in a Docker container with security flags required for Chromium to function on GitHub Actions runners (`--security-opt seccomp=unconfined` and `--ipc=host`). These flags are automatically configured by gh-aw version 0.41.0 and later.
+
 ## Built-in MCP Tools
 
 ### Agentic Workflows (`agentic-workflows:`)
diff --git a/docs/src/content/docs/troubleshooting/common-issues.md b/docs/src/content/docs/troubleshooting/common-issues.md
@@ -209,6 +209,31 @@ await mcp__playwright__browser_run_code({
 
 See the [Playwright Tool documentation](/gh-aw/reference/tools/#playwright-tool-playwright) for complete details.
 
+### Playwright MCP Initialization Failure (EOF Error)
+
+**Error Message:**
+
+```text
+Failed to register tools error="initialize: EOF" name=playwright
+Tool 'browser_navigate' does not exist
+```
+
+**Cause:** The Playwright MCP server starts but fails during initialization because the Chromium browser crashes before tool registration completes. This happens when required Docker security flags are missing, causing the MCP init pipe to close (EOF) before tools are registered.
+
+**Solution:** This issue was fixed in version 0.41.0 and later. The Playwright container now includes the required Docker security flags (`--security-opt seccomp=unconfined` and `--ipc=host`) for Chromium to function properly on GitHub Actions runners.
+
+**If you're on an older version:**
+
+Upgrade to version 0.41.0 or later:
+
+```bash wrap
+gh extension upgrade gh-aw
+```
+
+**Why this happens:**
+
+GitHub Actions runners use security constraints that prevent Chromium from starting without specific Docker flags. The browser tries to initialize during MCP server startup, crashes due to sandbox restrictions, and causes the MCP protocol to fail before any tools are registered. The gateway may still report the server as "connected" because the container started successfully, but no tools are available because initialization never completed.
+
 ## Permission Issues
 
 ### Write Operations Fail
diff --git a/pkg/workflow/mcp_config_playwright_renderer.go b/pkg/workflow/mcp_config_playwright_renderer.go
@@ -20,9 +20,16 @@
 // MCP image (mcr.microsoft.com/playwright/mcp). The container is configured with:
 //   - --init flag for proper signal handling
 //   - --network host for network access
+//   - --security-opt seccomp=unconfined for Chromium sandbox compatibility
+//   - --ipc=host for shared memory access required by Chromium
 //   - Volume mounts for log storage
 //   - Output directory for screenshots and artifacts
 //
+// GitHub Actions compatibility:
+// The security flags are required for Chromium to function properly on GitHub Actions
+// runners. Without these flags, Playwright initialization fails with "EOF" error because
+// Chromium crashes during startup due to sandbox constraints.
+//
 // Domain restrictions:
 // For security, Playwright is restricted to specific allowed domains configured
 // in the workflow frontmatter. These domains are passed via:
@@ -106,7 +113,10 @@ func renderPlaywrightMCPConfigWithOptions(yaml *strings.Builder, playwrightConfi
 
 	// Docker runtime args (goes before container image in docker run command)
 	// These are additional flags for docker run like --init and --network
-	dockerArgs := []string{"--init", "--network", "host"}
+	// Add security-opt and ipc flags for Chromium browser compatibility in GitHub Actions
+	// --security-opt seccomp=unconfined: Required for Chromium sandbox to function properly
+	// --ipc=host: Provides shared memory access required by Chromium
+	dockerArgs := []string{"--init", "--network", "host", "--security-opt", "seccomp=unconfined", "--ipc=host"}
 	if inlineArgs {
 		yaml.WriteString("                \"args\": [")
 		for i, arg := range dockerArgs {
