Generated MCP Gateway command uses --network host with gh-aw-mcpg images that require published ports

[zarenner]

Summary

gh-aw currently generates an MCP Gateway Docker command with --network host, but current gh-aw-mcpg containerized startup validation requires the configured gateway port to appear in .NetworkSettings.Ports with a HostPort. Docker host networking intentionally leaves .NetworkSettings.Ports={}, so this combination fails on Linux/DinD runners where the gateway can discover its own container ID.

Observed failure

Observed on a Linux self-hosted runner hosted inside an Ubuntu container with DinD.

Failure excerpt from the Start MCP Gateway step:

[INFO] Starting gateway with container: docker run -i --rm --network host ... ghcr.io/github/gh-aw-mcpg:v0.3.25
[INFO] Gateway started with PID: 2103
[ERROR] ERROR: Gateway process (PID: 2103) exited during initialization
[INFO] Container ID: 4f4979f2cb8e...
[INFO] Docker daemon is accessible
[INFO] Required environment variables are set
[INFO] Set DOCKER_API_VERSION=1.54 (server current)
[ERROR] Port 8080 is not exposed from the container
[ERROR] Add port mapping: -p <host_port>:8080

Current upstream generator behavior

Current main still builds the gateway command this way in pkg/workflow/mcp_setup_generator.go:

containerCmd.Grow(2048)
containerCmd.WriteString("docker run -i --rm --network host")
containerCmd.WriteString(" --add-host host.docker.internal:127.0.0.1")

Current generated/golden workflows also reference ghcr.io/github/gh-aw-mcpg:v0.3.26 with --network host.

Why this fails only in some environments

gh-aw-mcpg only performs container-specific validation if it can determine its own container ID:

CONTAINER_ID=$(get_container_id) || true

if [ -n "$CONTAINER_ID" ]; then
    validate_port_mapping "$CONTAINER_ID"
    validate_stdin_interactive "$CONTAINER_ID"
    validate_container_config "$CONTAINER_ID"
    validate_log_directory_mount "$CONTAINER_ID"
fi

On a Linux DinD runner, the gateway can log a container ID and then validate port mappings. On some local/Docker Desktop or other smoke environments, container ID detection can fail, the script logs Could not determine container ID, and the incompatible validation block is skipped.

That likely explains why this can pass smoke coverage while failing on a Linux self-hosted runner container with DinD.

Docker behavior

Host networking cannot satisfy the current port-mapping validation. Even when -p is supplied alongside --network host, Docker discards the published ports from the network settings:

docker create --entrypoint true --network host -p 18083:8080 ghcr.io/github/gh-aw-mcpg:v0.3.26

Observed metadata:

WARNING: Published ports are discarded when using host network mode
NetworkSettings.Ports={}
HostConfig.PortBindings={"8080/tcp":[{"HostIp":"","HostPort":"18083"}]}
NetworkMode=host

So simply appending -p while retaining --network host will not fix this.

Expected behavior

Either:

1. gh-aw should generate a non-host-networked gateway command with an actual published port, and preserve the required connectivity to safe outputs / host services; or
2. gh-aw-mcpg should accept HostConfig.NetworkMode=host during validation.

Given the generator has used --network host for some time, the least disruptive short-term fix may be in gh-aw-mcpg; however, gh-aw should have smoke coverage for the generated gateway command on Linux/DinD where container ID discovery succeeds.

Companion issue

Gateway-side validation issue: github/gh-aw-mcpg#7647

[zarenner]

Additional context after checking docs/specs/tests:

I did not find an ADR that formally says the outer MCP Gateway container must use host networking or must be configurable. I did find several implementation-level assumptions that treat host networking as intentional today:

• actions/setup/sh/start_mcp_gateway.sh health check comments say the gateway uses --network host, so the runner-side health check uses localhost even when agent-side clients use host.docker.internal.
• actions/setup/sh/start_mcp_gateway_test.sh has validation tests built around docker run -i --rm --network host ... commands.
• pkg/workflow/mcp_setup_generator.go hard-codes docker run -i --rm --network host before appending any sandbox.mcp fields.

There is also some doc tension: docs/src/content/docs/introduction/architecture.mdx describes the gateway as publishing a host port mapped to a container port, which is bridge/published-port language rather than host-network language.

So I do not think the necessary conclusion is specifically "make network mode configurable". The core gh-aw issue is that current generated gateway startup is incompatible with current gh-aw-mcpg validation when the gateway can discover its own Docker container ID. The fix could be in gh-aw-mcpg accepting HostConfig.NetworkMode=host, or in gh-aw changing the gateway topology and associated health/client routing assumptions.

[lpcox]

Tracking issue created in gh-aw-mcpg: github/gh-aw-mcpg#7647

The gh-aw-mcpg side fix (skip validate_port_mapping when HostConfig.NetworkMode=host) has been implemented and shipped in v0.3.27. The upstream generator change in gh-aw (switching away from --network host) remains the longer-term fix to prevent similar environment-specific validation gaps.

Generated by Gateway Issue Dispatcher · 92.7 AIC · ⊞ 32.8K · ◷

[Tarekchehahde]

Fork PR: Tarekchehahde#11

Upstream compare: main...Tarekchehahde:gh-aw:fix/39692-mcp-gateway-bridge-port

Approach: Always generate bridge + published port for MCP gateway (including sudo: true paths). Host networking leaves NetworkSettings.Ports={}, which fails gh-aw-mcpg validation when container ID discovery succeeds.

Local tests: go test -tags=integration ./pkg/workflow/... -run TestMCPGatewayDockerCommand — pass