What are Service Containers

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.

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 Overview

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.

Links and References

• GitHub Actions: Service Containers
• actions/checkout
• actions/setup-node
• MongoDB Docker Hub