How do you set up a Docker container service for integration tests using services: in GitHub Actions?

The services: block on a job starts Docker containers as side-cars alongside the job's steps. This lets you spin up a real PostgreSQL, Redis, or any other service that your integration tests need — without mocking — using the same Docker images you would use in production.

jobs:
  integration-tests:
    runs-on: ubuntu-latest

    services:
      postgres:
        image: postgres:16
        env:
          POSTGRES_USER: testuser
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb
        ports:
          - 5432:5432
        options: >-
          --health-cmd pg_isready
          --health-interval 10s
          --health-timeout 5s
          --health-retries 5

      redis:
        image: redis:7
        ports:
          - 6379:6379

    steps:
      - uses: actions/checkout@v4

      - name: Run integration tests
        run: ./gradlew integrationTest
        env:
          DB_URL: jdbc:postgresql://localhost:5432/testdb
          DB_USER: testuser
          DB_PASS: testpass
          REDIS_URL: redis://localhost:6379

A few important details:

• Health checks via options: --health-cmd ... ensure GitHub waits for the service to be ready before steps begin. Without this your tests may start before PostgreSQL finishes initialising.
• Port mapping: the service is accessible from steps at localhost:<host-port>. The host port and container port do not need to match but must be mapped in ports:.
• Container jobs: if your job itself runs inside a container (container: key), services are accessible by the service label name (e.g. postgres:5432) rather than localhost, because Docker networking uses the service name as DNS.
• Services are only supported on GitHub-hosted Linux runners and self-hosted Linux runners with Docker available.

Invest now in Acorns!!! 🚀
Join Acorns and get your $5 bonus!

Acorns is a micro-investing app that automatically invests your "spare change" from daily purchases into diversified, expert-built portfolios of ETFs. It is designed for beginners, allowing you to start investing with as little as $5. The service automates saving and investing. Disclosure: I may receive a referral bonus.

Invest now!!! Get Free equity stock (US, UK only)!

Use Robinhood app to invest in stocks. It is safe and secure. Use the Referral link to claim your free stock when you sign up!.

The Robinhood app makes it easy to trade stocks, crypto and more.

Webull! Receive free stock by signing up using the link: Webull signup.