How to make Gitlab CI/CD run container with some custom variables?

Question

i have a job that starts android UI-tests on GitLab CI/CD. It somehow runs a container from image android-uitests:1.0 from registry. I don't know where and how Gitlab CI/CD runs that image using command "docker run ...", but i need to extend that command and i want to pass some variables (or arguments) in this command.

Here below example of command that i want Gitlab to do:

docker run -d \
       -t \
       --privileged \
       -e "SNAPSHOT_DISABLED"="true" \
       -e "QTWEBENGINE_DISABLE_SANDBOX"=1 \
       -e "WINDOW"="true" \
       --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw" \
       -p 5555:5555 -p 5554:5554 -p 5901:5901 \
       --name emulator \
       android-uitest:1.0

this is a stage and its job with image

ui-tests:
  image: registry.myproject:5000/android-uitests:1.0
  stage: ui-tests
  only:
    - merge_requests
    - schedules
  when: manual
  script:
    - bash /run-emulator.sh
    - adb devices
    - adb shell input keyevent 82
    - adb shell settings put global window_animation_scale 0 &
    - adb shell settings put global transition_animation_scale 0 &
    - adb shell settings put global animator_duration_scale 0 &
    - ./gradlew mobile:connectedDevDebugAndroidTest -Pandroid.testInstrumentationRunnerArguments.package=app.online.tests.uitests
  tags:
    - androidtest

So another words i want to configure that "under the hood docker run command" that runs my image.

Tell me please how to do that?

Answer 1

Considering you're using a Docker container, I'll assume you're using a Gitlab Runner on Docker executor mode, which means you're essentially running a similar script to this when you don't specify a docker image to run the CI job:

image: docker:19.03.13

variables:
  DOCKER_TLS_CERTDIR: "/certs"

services:
  - docker:19.03.13-dind

script:
  - (your commands)

To understand what's going on, let's break it in multiple steps:

    image: docker:19.03.13
(...)
    services:
      - docker:19.03.13-dind

docker-19.03.13-dind, what's the difference to docker:19.03.13?

why is it a service instead of an image?

DIND means Docker-in-Docker, this part of Gitlab's documentation can explain it in further technical details, but what is important to understand from this part is what is a service on Gitlab's CI context and why they have to specify an additional Docker image when already using a Docker image as a default environment. When you write a service on Gitlab CI, you are able to use its command while you're inside an existing container. e.g. when you want to connect a PostgreSQL (database) container to a backend container you're building, but without having to set up a docker-compose or multiple containers.

Using a docker service to run together with a docker image, it means you can directly use docker run within your job without any additional setup. This previous StackOverflow question explains this question further.

Back to your code, instead of deploying your registry image as a job directly:

ui-tests:
  image: registry.myproject:5000/android-uitests:1.0

You may want to first, build your container and upload it to your registry:

image: docker:19.03.12

services:
  - docker:19.03.12-dind

variables:
  # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
  DOCKER_HOST: tcp://docker:2376
  DOCKER_TLS_CERTDIR: "/certs"

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY
  - docker build $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
  - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
  - docker push $CI_REGISTRY_IMAGE:latest

This snippet will build your Dockerfile in the root folder of your repository and upload it to your Gitlab private (or public, if your project is set as public) image registry. Now you can specify an additional job specifically to do what you want:

Final example

image: docker:19.03.12
stages:
  - build
  - release
services:
  - docker:19.03.12-dind

variables:
  # Use TLS https://docs.gitlab.com/ee/ci/docker/using_docker_build.html#tls-enabled
  DOCKER_HOST: tcp://docker:2376
  DOCKER_TLS_CERTDIR: "/certs"

before_script:
  - docker login -u $CI_REGISTRY_USER -p $CI_REGISTRY_PASSWORD $CI_REGISTRY

build:
  stage: build
  script:
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker build --cache-from $CI_REGISTRY_IMAGE:latest --tag $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA --tag $CI_REGISTRY_IMAGE:latest .
    - docker push $CI_REGISTRY_IMAGE:$CI_COMMIT_SHA
    - docker push $CI_REGISTRY_IMAGE:latest

deploy:
  stage: release
  script:
    - docker pull $CI_REGISTRY_IMAGE:latest || true
    - docker run -d -t --privileged -e "SNAPSHOT_DISABLED"="true" -e "QTWEBENGINE_DISABLE_SANDBOX"=1    -e "WINDOW"="true" --volume="/tmp/.X11-unix:/tmp/.X11-unix:rw"    -p 5555:5555 -p 5554:5554 -p 5901:5901 --name emulator $CI_REGISTRY_IMAGE:latest

Why are you using $VARIABLES?

In case of an environment variable may sound confusing, here's the list of default environment variables Gitlab generates for every job it creates.

The last example I cited will result in a Docker container running in the same machine your executor is registered, with the environment variables you have specified.

If you need a practical example, you can use this gitlab-ci.yml of a project of mine as reference.