Skip to main content
Service containers are Docker containers that provide a portable way to host supporting services—like databases or caches—for your GitHub Actions workflows. They enable your jobs to spin up dependencies on demand, ensuring consistency across environments.

​
Table of Contents

  1. Basic Workflow Without Services
  2. How to Add a Service Container
  3. Running Jobs Inside a Container with Services
  4. Service Containers Overview
  5. Summary
  6. Links and References

​
Basic Workflow Without Services

This example workflow checks out code, installs Node.js, pulls dependencies, and runs tests without any external services. 
name: My Awesome App
on: push

jobs:
  unit-testing:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm install

      - name: Run Tests
        run: npm test

​
How to Add a Service Container

To include a service container—such as MongoDB—you define it under the services key. Map the container port to a runner port, then connect to it via localhost. 
name: My Awesome App
on: push

jobs:
  unit-testing:
    runs-on: ubuntu-latest
    services:
      mongodb-service:
        image: mongo:latest
        ports:
          - 12345:27017

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '20'

      - name: Install Dependencies
        run: npm install

      - name: Run Tests
        env:
          MONGODB_HOST: localhost
          MONGODB_PORT: 12345
        run: npm test
In this configuration:
  • The GitHub runner uses Docker to start a MongoDB container named mongodb-service.
  • Port 27017 inside the container is exposed on port 12345 of the runner.
  • Tests connect to localhost:12345 to reach MongoDB.
Always make sure the port you map on the runner (e.g., 12345) is not in use by other services.

​
Running Jobs Inside a Container with Services

You can run the entire job in a container and still attach service containers alongside it. Below, a Node.js container runs the job, and MongoDB is available via hostname. 
name: My Awesome App
on: push

jobs:
  unit-testing:
    runs-on: ubuntu-latest

    # Primary job container
    container:
      image: ghcr.io/node-and-packages:20

    # Additional service container
    services:
      mongodb-service:
        image: mongo:latest

    steps:
      - name: Checkout Code
        uses: actions/checkout@v3

      - name: Install Dependencies
        run: npm install

      - name: Run Tests
        env:
          MONGODB_HOST: mongodb-service
          MONGODB_PORT: 27017
        run: npm test
Key points:
  • The job runs inside ghcr.io/node-and-packages:20.
  • mongodb-service starts on the same Docker network.
  • Hostname mongodb-service resolves to the MongoDB container on port 27017.
Service containers share a user-defined bridge network. Do not rely on localhost inside the primary container; use the defined service hostname.

​
Service Containers Overview

FeatureDescriptionExample
Port MappingExpose container ports to the runner or other jobs.ports: [ 12345:27017 ]
Hostname ResolutionServices are reachable by their service key.MONGODB_HOST: mongodb-service
Custom ImagesUse specific versions or private registry images.image: myregistry/mongo:5.0
Network IsolationRuns in a user-defined bridge for security and speed.Containers cannot access runner network unless mapped.

​
Summary

Service containers in GitHub Actions allow you to:
  • Spin up databases, caches, or message queues alongside your workflows.
  • Connect to services via mapped ports or hostnames.
  • Run jobs directly on a runner or inside a dedicated container while still leveraging supporting services.
By integrating service containers, you ensure consistent, reproducible test environments for your CI/CD pipelines.

Watch Video