What Is a Service Container in GitHub Actions?

A service container is a Docker container GitHub runs next to your job, typically a database or queue your tests connect to.

Integration tests often need a real Postgres or Redis. Service containers spin up those dependencies as containers for the life of the job, networked so your steps can reach them.

What it is

A container declared under a job's services: key. GitHub starts it before the steps run and makes it reachable over the job's network.

jobs:
  test:
    runs-on: ubuntu-latest
    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_PASSWORD: pw
        ports: ['5432:5432']
    steps:
      - run: psql -h localhost -U postgres -c '\\l'

How it works

GitHub launches each service container, maps the ports you request, and waits before running steps. Your steps connect via localhost and the mapped port (or by service name on container jobs).

Health and readiness

You can add health check options so GitHub waits until the service is actually ready, avoiding flaky connection errors at the start of a job.

Why it matters

Service containers give tests a real dependency without provisioning external infrastructure. They are reproducible, isolated, and torn down automatically when the job ends.

Related concepts

Service containers run on the same runner as the job and complement actions like actions/checkout for full integration setups.

Key takeaways

• A service container is a Docker dependency run beside the job.
• Declare it under services: with an image and ports.
• Use health checks so steps wait until it is ready.

Related guides