jobs.<job_id>.services

jobs.<job_id>.services is a Preview feature.

A Preview feature:

Has not undergone end-to-end testing with CloudBees products.
Is provided without service-level agreements (SLA), and therefore does not include CloudBees' commitment to functionality or performance.
May impact other stable areas of the product when used.
May have limited documentation.
May not be feature-complete during the Preview period.
May graduate from Preview to a supported feature or be removed from the product.
May introduce breaking changes that prevent upgrades due to incompatibility with future development.

Product features and documentation are frequently updated. If you find an issue or have a suggestion, please contact CloudBees Support.

Use jobs.<job_id>.services to run a service in a separate container alongside the job for the duration of the run, providing functionality such as a database or application server.

Usage example

This example starts a PostgreSQL service, sets credentials with environment variables, and verifies connectivity with a simple SQL query.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: Postgres service example
on: push

jobs:
  test:

    services:                         #Declares service containers that run alongside the job.
      postgres:                       #Names the PostgreSQL service.
        image: postgres:17-alpine3.20 #Pins the service image version.
        env:                          #Provides environment variables consumed by the postgres image at startup.
          POSTGRES_USER: testuser     #Sets default user, password, and database created by the service.
          POSTGRES_PASSWORD: testpassword
          POSTGRES_DB: testdb

    steps:
      - name: Run tests against postgres db
        uses: docker://postgres:17
        env:
          DATABASE_URL: postgres://testuser:testpassword@localhost:5432/testdb  #Connects to the service on localhost:5432 using the configured credentials.
        run: |
          psql -h localhost -U testuser -d testdb -c "SELECT 'Hello, PostgreSQL!' AS greeting;"▼

jobs.<job_id>.services.<service_id>

Use jobs.<job_id>.services.<service_id> to uniquely identify a service.

Usage example

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

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: MySQL service example
on:
  push:

jobs:
  test:                                  #The job ID `test` defines a job that runs when code is pushed to the repository.
    services:
      my-service:                        #The `my-service` service ID uniquely identifies a MySQL service container used in the test job.
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: examplepassword
          MYSQL_DATABASE: exampledb
        args: "--default-authentication-plugin=mysql_native_password"

    steps:
      - name: Wait for MySQL service     #This step waits for the MySQL service to be ready by repeatedly pinging it until it responds.
        uses: docker://mysql:8.0
        run: |
          until mysqladmin ping -h 127.0.0.1 --silent; do
            echo "Waiting for database connection..."
            sleep 2
          done
        env:
          MYSQL_PWD: examplepassword

      - name: Run a query                #This step sends a SQL query to the `my-service` to list all available databases.
        uses: docker://mysql:8.0
        run: |
          echo "SHOW DATABASES;" | mysql -u root -h 127.0.0.1
        env:
          MYSQL_PWD: examplepassword▼

jobs.<job_id>.services.<service_id>.args

Use jobs.<job_id>.services.<service_id>.args to set the arguments passed to the ENTRYPOINT of the service container. Follow these args specification guidelines:

Enter the args parameter as Unicode string.
Arguments containing spaces must be surrounded by double quotes ("").
An escape character \ is supported. Use \ for arguments that contain spaces. For example, surround an argument using \" or "\"".

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

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

Usage example

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

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: MySQL service example
on: push

jobs:
  test:
    services:
      my-service:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: examplepassword
          MYSQL_DATABASE: exampledb
        args: "--default-authentication-plugin=mysql_native_password"

    steps:
      - name: Wait for MySQL service to be ready
        uses: docker://mysql:8.0
        run: |
          until mysqladmin ping -h 127.0.0.1 --silent; do
            echo "Waiting for database connection..."
            sleep 2
          done
        env:
          MYSQL_PWD: examplepassword

      - name: Run a query
        uses: docker://mysql:8.0
        run: |
          echo "SHOW DATABASES;" | mysql -u root -h 127.0.0.1
        env:
          MYSQL_PWD: examplepassword▼

jobs.<job_id>.services.<service_id>.env

Use jobs.<job_id>.services.<service_id>.env to set environment variables for the service.

For example, env defined for a service overrides the job and workflow env variables. For details related to defining env for the entire workflow refer to: jobs.<job_id>.env.

Usage example

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

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: MySQL service example
on: push

jobs:
  test:
    services:
      my-service:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: examplepassword
          MYSQL_DATABASE: exampledb
        args: "--default-authentication-plugin=mysql_native_password"

    steps:
      - name: Wait for MySQL service to be ready
        uses: docker://mysql:8.0
        run: |
          until mysqladmin ping -h 127.0.0.1 --silent; do
            echo "Waiting for database connection..."
            sleep 2
          done
        env:
          MYSQL_PWD: examplepassword

      - name: Run a query
        uses: docker://mysql:8.0
        run: |
          echo "SHOW DATABASES;" | mysql -u root -h 127.0.0.1
        env:
          MYSQL_PWD: examplepassword▼

jobs.<job_id>.services.<service_id>.image

Use jobs.<job_id>.services.<service_id>.image to specify an image.

Specify a Docker image

Use jobs.<job_id>.services.<service_id>.image to add a Docker image to a workflow job.

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

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: MySQL service example
on: push

jobs:
  test:
    services:
      my-service:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: examplepassword
          MYSQL_DATABASE: exampledb
        args: "--default-authentication-plugin=mysql_native_password"

    steps:
      - name: Wait for MySQL service to be ready
        uses: docker://mysql:8.0
        run: |
          until mysqladmin ping -h 127.0.0.1 --silent; do
            echo "Waiting for database connection..."
            sleep 2
          done
        env:
          MYSQL_PWD: examplepassword

      - name: Run a query
        uses: docker://mysql:8.0
        run: |
          echo "SHOW DATABASES;" | mysql -u root -h 127.0.0.1
        env:
          MYSQL_PWD: examplepassword▼

Specify a private image

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

Usage example

In the following example, an image stored in Amazon Web Services (AWS) Elastic Container Registry (ECR) is added to the workflow job.

apiVersion: automation.cloudbees.io/v1alpha1
kind: workflow
name: AWS ECR example
on: push

jobs:
  my-job:
    permissions:
      scm-token-own: read
      id-token: write
      services:
    my-service:
        image: mysql:8.0
        env:
          MYSQL_ROOT_PASSWORD: {{ secrets.MYSQL_PASSWORD }}
          MYSQL_DATABASE: exampledb
        args: "--default-authentication-plugin=mysql_native_password"
    steps:
      - name: Checkout
        uses: https://github.com/cloudbees-io/checkout@v1
      - name: Log in to AWS
        uses: https://github.com/cloudbees-io/configure-aws-credentials@v1
        id: aws-login
        with:
          aws-region: us-east-1
          role-to-assume: {{vars.AWS_ROLE }}
          role-duration-seconds: "3600"
      - name: Wait for MySQL service to be ready
        uses: {{ secrets.AWS_ECR_HOSTNAME }}
        run: |
          until mysqladmin ping -h 127.0.0.1 --silent; do
            echo "Waiting for database connection..."
            sleep 2
          done
        env:
          MYSQL_PWD: {{ secrets.MYSQL_PASSWORD }}
      - name: Run a query
        uses: {{ secrets.AWS_ECR_HOSTNAME }}
        run: |
          echo "SHOW DATABASES;" | mysql -u root -h 127.0.0.1
        env:
          MYSQL_PWD: {{ secrets.MYSQL_PASSWORD }}▼