Working with Docker Services

1. Configuring Docker Services

Property	Description	Values	Notes
services	List of Docker services to run with the job	`['image:tag', ...]`	Each service runs in a separate container
image	Primary container image for the job	`string`	Must be accessible to the runner
variables	Environment variables to pass to services	`{key: value}`	Available in service containers
alias	Alias for the service container	`string`	Used to reference the service in job scripts
command	Override default command for service container	`string`	Executed when the service starts

Example: Configuring a PostgreSQL Service

services:
  - name: postgres:13
    alias: db
    variables:
      POSTGRES_PASSWORD: mysecretpassword

Note: Services are started before the job script and stopped after.

Warning: Ensure service images are publicly accessible or cached in the runner.

2. Setting Service Aliases

Property	Description	Example
alias	Defines an alias for the service container, allowing other services or jobs to reference it by name.	`alias: database`
image	Specifies the Docker image to use for the service container.	`image: postgres:13`
variables	Environment variables to set inside the service container.	`variables: POSTGRES_PASSWORD: secret`

Example: Defining a service with an alias

services:
  - name: postgres:13
    alias: db-service
    variables:
      POSTGRES_PASSWORD: mysecretpassword

Note: The alias allows other jobs or services to connect using the alias name instead of the default container name.

3. Using Database Services

Service	Image	Environment Variables	Notes
postgres	`postgres:15`	`POSTGRES_PASSWORD=postgres`, `POSTGRES_USER=postgres`	Default user is `postgres`, password is `postgres`
mysql	`mysql:8.0`	`MYSQL_ROOT_PASSWORD=root`, `MYSQL_DATABASE=testdb`	Root password is `root`, default database is `testdb`
redis	`redis:7-alpine`	`REDIS_PASSWORD=redis`	Password is optional, default port is `6379`

Example: Using PostgreSQL service in a job

services:
  - postgres:15
variables:
  POSTGRES_DB: testdb
  POSTGRES_USER: testuser
  POSTGRES_PASSWORD: testpass
  POSTGRES_PORT: 5432

Note: The service container is started before the job and stopped after the job completes.

Warning: Ensure that your database service is configured to accept connections from the job container.

4. Using Redis Service

Property	Value	Description
services	`redis:latest`	Defines the Redis service to be used in the job
variables	`REDIS_URL=redis://redis:6379`	Environment variable to connect to Redis instance

Example: Using Redis in a Job

job_with_redis:
  image: node:16
  services:
    - redis:latest
  variables:
    REDIS_URL: redis://redis:6379
  script:
    - echo "Using Redis at $REDIS_URL"

Note: The Redis service is accessible via the redis hostname from within the job container.

5. Using Elasticsearch Service

Property	Value	Description
services	`elasticsearch:7`	Defines the Elasticsearch service to run in the job
variables.ELASTICSEARCH_URL	`http://elasticsearch:9200`	URL to connect to the Elasticsearch instance

Example: Elasticsearch Service Configuration

job_name:
  image: alpine:latest
  services:
    - elasticsearch:7
  variables:
    ELASTICSEARCH_URL: http://elasticsearch:9200
  script:
    - echo "Elasticsearch is running at $ELASTICSEARCH_URL"

Note: Elasticsearch service requires at least 256MB of memory to run properly. Ensure your GitLab runner has sufficient resources.

6. Using Docker-in-Docker Service

Option	Values	Notes
services	`dind`	Alias for `docker:dind`
image	`docker:dind`	Docker-in-Docker image
variables	`DOCKER_HOST`	Set to `tcp://localhost:2375`

Example: Using Docker-in-Docker in a Job

job_with_dind:
  image: docker:latest
  services:
    - docker:dind
  variables:
    DOCKER_HOST: tcp://localhost:2375
  script:
    - docker info
    - docker run hello-world

Note: The dind service requires the docker image to be used as the job's primary image.

Warning: Docker-in-Docker jobs are slower and use more resources than regular jobs.

7. Configuring Service Health Checks

Property	Description	Default	Notes
health_check	Defines the health check configuration for a service	`null`	Used in `services` section of a job
health_check.interval	How often to check the service health (e.g., `10s`)	`1s`	Supports `s`, `m`, `h`
health_check.timeout	Maximum time to wait for a health check response (e.g., `30s`)	`10s`	Must be less than `interval`
health_check.start_period	Time to wait before starting health checks (e.g., `30s`)	`0s`	Useful for services that take time to start up

Example: Configuring a service with health checks

job_with_health_check:
  image: alpine:latest
  services:
    - name: postgres:13
      alias: db
      health_check:
        interval: 10s
        timeout: 5s
        start_period: 30s

Note: Health checks are only supported in GitLab CI/CD when using Docker-in-Docker (DinD) or Docker executor.

8. Setting Service Variables

Variable	Value	Description
CI_REGISTRY_USER	`gitlab-ci-token`	Username for Docker registry authentication
CI_REGISTRY_PASSWORD	`$CI_REGISTRY_PASSWORD`	Password for Docker registry authentication
CI_REGISTRY_IMAGE	`registry.gitlab.com/group/project/image`	Full image name for Docker registry

Example: Using Service Variables in a Job

job_with_service:
  image: alpine
  services:
    - name: postgres:13
      alias: db
  variables:
    POSTGRES_DB: test_db
    POSTGRES_USER: test_user
    POSTGRES_PASSWORD: test_password
  script:
    - echo "Using database: $POSTGRES_DB"
    - apk add --no-cache postgresql-client
    - psql -h db -U $POSTGRES_USER -d $POSTGRES_DB << EOF
      SELECT version();
    EOF

Note: Service variables are automatically set by GitLab CI/CD when a service is defined. These variables can be overridden in the variables section of a job.

9. Using Service Entrypoint

Property	Description	Default	Notes
entrypoint	Override the default entrypoint of the service image	`["/docker-entrypoint.sh"]`	Can be a string or array of strings

Example: Setting a custom entrypoint

services:
  database:
    image: postgres:13
    entrypoint: ["/usr/bin/custom-entrypoint.sh", "--verbose"]

Note: The entrypoint is set using the Docker ENTRYPOINT instruction. It overrides the default entrypoint of the image.

10. Networking Between Job and Services

Service	Network Access	Notes
service.name	`gitlab-docker-runner`	Container name for the service
service.image	`postgres:13`	Docker image used to run the service
service.alias	`db`	Alias used to connect from job to service
service.variables	`POSTGRES_DB=test_db`	Environment variables passed to service container

Example: Connecting to a Database Service

services:
  - name: postgres:13
    alias: db
    variables:
      POSTGRES_DB: test_db
      POSTGRES_USER: test_user
      POSTGRES_PASSWORD: test_pass

job:
  script:
    - echo "Connecting to database at $DB_PORT_5432_TCP_ADDR"

Note: Services are accessible via their alias from within the job container.

Warning: Ensure that service containers are configured with appropriate environment variables to allow connections.