Postgres connection refused in GitHub Actions: check network location and readiness

Find where the test process runs

An application team has a green local database test but CI fails before executing its assertions. Inspect whether the job has a container setting or runs directly on the runner. In a container job, localhost means that job container, not the Postgres service. GitHub's example connects through the service label postgres. A host-runner job instead uses localhost or 127.0.0.1 and needs the service port published to the host.

• Compare the configured host and port without printing the password or full connection string.
• Keep the first connection error distinct from authentication or schema errors.

Prove the service became ready

A container being created is not proof the database accepts connections. GitHub documents a pg_isready health check with an interval, timeout and retry limit. Inspect the service health and existing redacted startup logs. A fixed sleep is a guess; readiness evidence is the better boundary. Verify Linux and Docker prerequisites before diagnosing an application database client.

• Use disposable database credentials only on the authorised CI route.
• Do not point the test at production to make the connection succeed.

Then check the application setup

After connectivity works, check the intended test database, schema setup and synthetic fixtures. Connection refusal, wrong password and missing table are separate problems; a hostname change cannot prove migrations were applied. Preserve the failing integration assertions instead of replacing the database-backed test with a mock just to obtain a green job.

• Retain any application-level failure revealed after connectivity is fixed.
• Keep service versions explicit enough for a reproducible comparison.

Acceptance evidence

The same workflow event and agreed revision start the disposable service, pass its health check, initialise the test schema and execute the named assertions. Include one deliberately failing assertion to demonstrate that the test still detects failure. This proves the selected CI path, not production database health. Send redacted job location and error initially; access and a repair quote are agreed separately.