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
Are used as hostnames for network connectivity
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

`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'
      DATABASE_URL: postgres://testuser:${{ secrets.DB_PASSWORD }}@database:5432/testdb
      LOG_LEVEL: debug▼

Environment variables:

Configure service behavior and runtime settings
Can reference other services by service ID as hostname
Should use string values (quoted numbers and booleans)
Are isolated to the service container

Service networking

Inter-service communication

Services can communicate with each other using service IDs as hostnames.

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

  api:
    image: myapi:latest
    env:
      DATABASE_HOST: database  # Service ID as hostname
      DATABASE_PORT: '5432'
      DATABASE_NAME: appdb

  cache:
    image: redis:6

  worker:
    image: myworker:latest
    env:
      REDIS_URL: redis://cache:6379  # Service ID 'cache' as hostname
      API_URL: http://api:3000       # Service ID 'api' as hostname▼

Network connectivity:

All services and job steps share the same network
Service IDs become DNS hostnames automatically
Default container ports are accessible (no port mapping needed)
Network is isolated from external access

Job step communication

Job steps can access services using service IDs as hostnames.

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 postgres -p 5432 -U postgres; do
            echo "Waiting for postgres..."
            sleep 2
          done

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

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

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 database; 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▼

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