Services syntax reference

Services syntax defines container-based services that run alongside job steps in CloudBees Unify workflows. Use this reference when configuring database containers, testing services, or other containerized dependencies for job execution.

Services is a Beta feature.

Services definition

`jobs.<job_id>.services`

Defines containerized services that run during job execution. Services start before job steps begin and are available throughout the job lifecycle.

jobs:
  test:
    services:
      database:
        image: postgres:13
        env:
          POSTGRES_PASSWORD: password
          POSTGRES_DB: testdb
        args:
          - --log-statement=all
      redis:
        image: redis:6-alpine
    steps:
      - name: Run tests against services
        run: npm test▼

Service configuration creates:

Network connectivity between services and job steps
Automatic service lifecycle management (start before steps, stop after job completion)
Environment variable access within services
Port mapping for service communication

`jobs.<job_id>.services.<service_id>`

Defines an individual service container. Service IDs must be unique within the job and follow standard naming conventions.

services:
  web-server:
    image: nginx:alpine
  database:
    image: mysql:8.0
  cache:
    image: redis:latest▼

Service identifiers:

Must start with a letter or underscore
Contain only alphanumeric characters, hyphens, and underscores
Should be descriptive of the service purpose

Service configuration properties

`image`

Specifies the container image to use for the service.

services:
  database:
    image: postgres:13.7

  custom-service:
    image: myregistry.com/myorg/custom-app:v1.2.3

  latest-redis:
    image: redis:latest▼

Image specification:

Use specific tags for reproducible builds (avoid latest in production)
Include registry prefix for private registries
Supports standard Docker image naming conventions
Image is pulled automatically if not available locally

`args`

Provides command-line arguments passed to the container entrypoint.

services:
  database:
    image: postgres:13
    args:
      - --log-statement=all
      - --log-min-duration-statement=0
      - --shared_preload_libraries=pg_stat_statements

  web-server:
    image: nginx:alpine
    args:
      - nginx
      - -g
      - daemon off;▼

Command arguments:

Are passed directly to the container’s entrypoint
Override default command arguments in the image
Use YAML array syntax for multiple arguments
Can include flags, options, and parameters

args specification guidelines:

Enter the args parameter as a Unicode string.
Arguments containing spaces must be surrounded by double quotes ("").
The escape character \ is supported.

When using CMD in the Dockerfile, use one of the following:

(Recommended) Delete any required arguments from CMD.
Define appropriate defaults so the service runs without specifying arguments.
If a --help flag is available, use that as the default.

`env`

Sets environment variables within the service container.

services:
  database:
    image: postgres:13
    env:
      POSTGRES_DB: testdb
      POSTGRES_USER: testuser
      POSTGRES_PASSWORD: testpass
      POSTGRES_HOST_AUTH_METHOD: trust

  api-service:
    image: myapp:latest
    env:
      NODE_ENV: test
      PORT: '3000'
      LOG_LEVEL: debug▼

Environment variables:

Configure service behavior and runtime settings
Should use string values (quoted numbers and booleans)
Are isolated to the service container

Service networking

Job step communication

To access service instances from within job steps, use localhost or 127.0.0.1 as the host and the corresponding port for the service.

jobs:
  integration-test:
    services:
      postgres:
        image: postgres:13
        env:
          POSTGRES_PASSWORD: testpass
          POSTGRES_DB: testdb

    steps:
      - name: Wait for database
        run: |
          until pg_isready -h 127.0.0.1 -p 5432 -U postgres; do
            echo "Waiting for postgres..."
            sleep 2
          done

      - name: Run database migrations
        env:
          DATABASE_URL: postgres://postgres:${{ secrets.DB_PASSWORD }}@localhost:5432/testdb
        run: npm run migrate

      - name: Run integration tests
        env:
          DATABASE_HOST: localhost
          DATABASE_PORT: '5432'
        run: npm run test:integration▼

Service identifier naming

Service identifiers in a job:

Must start with a letter or underscore
Contain only alphanumeric characters, hyphens, and underscores
Are referenced by their ID in the workflow definition

Service lifecycle

Startup order

All services start concurrently before any job steps begin
Services run throughout the entire job execution
Job steps wait for service startup (no automatic health checks)
Services stop automatically when the job completes

Health checking

Services do not include automatic health checks. Use job steps to verify service availability when needed.

services:
  database:
    image: postgres:13
    env:
      POSTGRES_PASSWORD: secret

steps:
  - name: Wait for database to be ready
    run: |
      echo "Waiting for database..."
      timeout 60 bash -c 'until pg_isready -h 127.0.0.1; do sleep 1; done'

  - name: Run tests
    run: npm test▼

Common service patterns

Database services

services:
  # PostgreSQL database
  postgres:
    image: postgres:13
    env:
      POSTGRES_DB: testdb
      POSTGRES_USER: testuser
      POSTGRES_PASSWORD: testpass
      POSTGRES_HOST_AUTH_METHOD: trust

  # MySQL database
  mysql:
    image: mysql:8.0
    env:
      MYSQL_DATABASE: testdb
      MYSQL_USER: testuser
      MYSQL_PASSWORD: testpass
      MYSQL_ROOT_PASSWORD: rootpass

  # MongoDB database
  mongodb:
    image: mongo:5.0
    env:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: password
      MONGO_INITDB_DATABASE: testdb▼

Cache and message queue services

services:
  # Redis cache
  redis:
    image: redis:6-alpine
    args:
      - redis-server
      - --appendonly
      - 'yes'

  # RabbitMQ message queue
  rabbitmq:
    image: rabbitmq:3-management-alpine
    env:
      RABBITMQ_DEFAULT_USER: admin
      RABBITMQ_DEFAULT_PASS: password

  # Elasticsearch
  elasticsearch:
    image: elasticsearch:7.17.0
    env:
      discovery.type: single-node
      ES_JAVA_OPTS: -Xms512m -Xmx512m▼

Testing and development services

services:
  # Mock API server
  mock-api:
    image: mockserver/mockserver:latest
    env:
      MOCKSERVER_PORT: '1080'

  # Local S3 (MinIO)
  minio:
    image: minio/minio:latest
    env:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    args:
      - server
      - /data

  # SMTP server for testing
  mailhog:
    image: mailhog/mailhog:latest▼

Specify a private image

Use jobs.<job_id>.services.<service_id>.image to add an image stored in a private registry. To learn more about using private images, refer to:

Example using an AWS ECR private image

jobs:
  my-job:
    permissions:
      scm-token-own: read
      id-token: write
    services:
      my-service:
        image: <AWS_ACCOUNT_ID>.dkr.ecr.<REGION>.amazonaws.com/<REPOSITORY>:<TAG>
        env:
          MYSQL_ROOT_PASSWORD: ${{ secrets.MYSQL_PASSWORD }}
          MYSQL_DATABASE: exampledb
    steps:
      - name: Log in to AWS
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        with:
          aws-region: us-east-1
          role-to-assume: ${{ vars.AWS_ROLE }}
          role-duration-seconds: "3600"
      - name: Wait for service
        run: |
          until mysqladmin ping -h 127.0.0.1 --silent; do
            echo "Waiting..."
            sleep 2
          done
        env:
          MYSQL_PWD: ${{ secrets.MYSQL_PASSWORD }}▼

Service limitations

Current limitations of the services feature:

Preview feature: Syntax and behavior may change
No port mapping: Services use default container ports only
No volumes: Persistent storage not supported
No health checks: Manual verification required in job steps
No privileged containers: Security restrictions apply
Resource limits: Subject to job execution environment constraints