GitHub Actions service container port not exposed to steps

A service container is reachable from steps that run directly on the runner via a mapped host port (localhost), or by service name when the job itself runs in a container. Missing the ports mapping or using the wrong host makes the connection refuse.

What this error means

A step cannot connect to the service (connection refused) even though the service container is running.

services:
  redis:
    image: redis:7
# no ports mapping declared
steps:
  - run: redis-cli -h localhost -p 6379 ping   # connection refused

Common causes

No ports mapping for runner-host access

Steps running on the runner need a host port mapping to reach the service via localhost.

Wrong host for container vs runner job

Container jobs reach services by service name; runner-host jobs reach them on localhost with a mapped port.

How to fix it

Map the port for runner-host steps

1. Add a ports mapping to expose the container port on the runner host.
2. Connect via localhost and the mapped port.

services:
  redis:
    image: redis:7
    ports:
      - 6379:6379
steps:
  - run: redis-cli -h localhost -p 6379 ping

Use the service name for container jobs

1. If the job runs in a container, connect using the service name as the host.
2. No host port mapping is needed in that case.

How to prevent it

• Declare ports when steps run on the runner host.
• Use the service name as host when the job runs in a container.

Related guides