Add github_runner_network_mode knob (host networking for host-side adb)

.github/workflows/lint-and-test.yml

@@ -37,6 +37,7 @@ jobs:
           - default
           - java-runner
           - android-runner
+          - android-runner-host
           - org-runner
       fail-fast: false
       max-parallel: 1

CHANGELOG.md

@@ -1,5 +1,13 @@
 # Changelog
 
+## [0.1.3] - 2026-05-27
+### Added
+- Added `github_runner_network_mode` variable (defaults to `default`) to control the runner container's Docker network mode. Set to `host` so the in-container `adb` client can reach an adb server running on the host at `127.0.0.1:5037`.
+- Added `android-runner-host` molecule scenario verifying host networking converges, is idempotent, and publishes no ports.
+
+### Changed
+- ADB port mapping is now omitted automatically when `github_runner_network_mode` is `host`, since `ports:` is invalid together with `network_mode: host`.
+
 ## [0.1.0] - 2025-11-12
 ### Breaking Changes
 - Removed `github_runner_install_docker` variable and Docker installation task

README.md

@@ -69,6 +69,7 @@ github_runner_java_mount_usb                | whether to mount usb devices (for
 github_runner_android                       | whether this is an android runner (defaults to false)
 github_runner_android_expose_adb_ports      | whether to expose ADB ports for android runners (defaults to false, requires github_runner_android to be true)
 github_runner_adb_port                      | the host port to map ADB to (defaults to 5037)
+github_runner_network_mode                  | the docker network mode for the runner container (defaults to "default"; set to "host" so the in-container adb client can reach an adb server running on the host at 127.0.0.1:5037)
 github_runner_java_image                    | the java / android runner image (defaults to compscidr/github-runner-android:latest)
 github_runner_non_java_image                | the non-java/android runner image (defaults to myoung34/github-runner:latest)
 github_runner_env_file                      | whether to use an env file for passing extra environment variables into the runner container (defaults to false)
@@ -90,10 +91,13 @@ The role provides two related but distinct variables for controlling runner beha
 
 - **`github_runner_android_expose_adb_ports`**: Controls whether ADB ports are exposed to the host. Only takes effect when `github_runner_android` is `true`. Set to `true` if you need to access ADB from outside the container (e.g., for physical device testing).
 
+- **`github_runner_network_mode`**: Controls the container's docker network mode. Defaults to `default`. Set to `host` when the **adb server runs on the host** (the host owns the USB phones) and the in-container `adb` client should reach it at `127.0.0.1:5037`. This shares the host's network namespace so a CI job can reboot its phones without the container losing them on USB re-enumeration. Note: `host` mode is incompatible with publishing `ports:`, so `github_runner_android_expose_adb_ports` is ignored (no port mapping is created) when `network_mode` is `host`.
+
 **Typical usage patterns:**
 - **Standard runner**: `github_runner_java: false`, `github_runner_android: false`
 - **Java/Android runner without ADB**: `github_runner_java: true`, `github_runner_android: true`, `github_runner_android_expose_adb_ports: false`
 - **Full Android runner with ADB**: `github_runner_java: true`, `github_runner_android: true`, `github_runner_android_expose_adb_ports: true`
+- **Android runner with host-side adb**: `github_runner_java: true`, `github_runner_android: true`, `github_runner_network_mode: host`
 
 ## Testing
 

galaxy.yml

@@ -8,7 +8,7 @@ description: "Installs github self hosted repo or org runners within a docker co
   can be a vanilla runner, or one with java / android installed."
 license_file: LICENSE
 readme: README.md
-version: 0.1.2
+version: 0.1.3
 repository: https://github.com/compscidr/ansible-github-runner
 tags:
     - github

molecule/android-runner-host/converge.yml

@@ -0,0 +1,7 @@
+---
+- name: Converge
+  hosts: all
+  become: true
+  gather_facts: true
+  roles:
+    - role: github_runner

molecule/android-runner-host/molecule.yml

@@ -0,0 +1,39 @@
+---
+dependency:
+  name: galaxy
+  options:
+    requirements-file: requirements.yml
+driver:
+  name: docker
+platforms:
+  - name: ubuntu-22.04-android-host
+    image: geerlingguy/docker-ubuntu2204-ansible:latest
+    command: ""
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock
+      - /sys/fs/cgroup:/sys/fs/cgroup:rw
+    cgroupns_mode: host
+    privileged: true
+    pre_build_image: true
+provisioner:
+  name: ansible
+  env:
+    ANSIBLE_ROLES_PATH: ${MOLECULE_PROJECT_DIRECTORY}/roles
+  playbooks:
+    prepare: ../default/prepare.yml
+    converge: converge.yml
+    verify: verify.yml
+  inventory:
+    host_vars:
+      ubuntu-22.04-android-host:
+        github_runner_personal_access_token: "test-token-android-host"
+        github_runner_name: "test-runner-android-host"
+        github_runner_repo: "test/repo"
+        github_runner_labels: "self-hosted,android"
+        github_runner_java: true
+        github_runner_android: true
+        github_runner_android_expose_adb_ports: true
+        github_runner_adb_port: 5037
+        github_runner_network_mode: host
+verifier:
+  name: ansible

molecule/android-runner-host/verify.yml

@@ -0,0 +1,55 @@
+---
+- name: Verify Android Runner (host networking)
+  hosts: all
+  gather_facts: false
+  become: true
+  tasks:
+    - name: Check if GitHub runner container is running
+      community.docker.docker_container_info:
+        name: "{{ github_runner_name }}"
+      register: runner_container
+
+    - name: Verify container exists
+      ansible.builtin.assert:
+        that:
+          - runner_container.exists
+        fail_msg: "GitHub runner container does not exist"
+        success_msg: "GitHub runner container exists"
+
+    - name: Verify container is running
+      ansible.builtin.assert:
+        that:
+          - runner_container.container.State.Running
+        fail_msg: "GitHub runner container is not running"
+        success_msg: "GitHub runner container is running"
+
+    - name: Verify container is using Android image
+      ansible.builtin.assert:
+        that:
+          - "'compscidr/github-runner-android' in runner_container.container.Config.Image"
+        fail_msg: "GitHub runner container is not using the Android image"
+        success_msg: "GitHub runner container is using the correct Android image"
+
+    - name: Debug HostConfig.NetworkMode
+      ansible.builtin.debug:
+        var: runner_container.container.HostConfig.NetworkMode
+
+    - name: Debug HostConfig.PortBindings
+      ansible.builtin.debug:
+        var: runner_container.container.HostConfig.PortBindings
+
+    - name: Verify container is using host network mode
+      ansible.builtin.assert:
+        that:
+          - runner_container.container.HostConfig.NetworkMode == 'host'
+        fail_msg: "GitHub runner container is not using host network mode"
+        success_msg: "GitHub runner container is using host network mode (correct)"
+
+    - name: Verify no ADB ports are published in host network mode
+      ansible.builtin.assert:
+        that:
+          - >-
+            (runner_container.container.HostConfig.PortBindings | default({}, true))
+            | length == 0
+        fail_msg: "Host network mode must not publish ports (ports: is invalid with network_mode: host)"
+        success_msg: "No ports published in host network mode (correct)"

roles/github_runner/defaults/main.yml

@@ -19,6 +19,10 @@ github_runner_env_filename: ".env"
 
 github_runner_adb_port: 5037
 
+# Docker network mode for the runner container. "host" lets the in-container
+# adb client reach an adb server running on the host at 127.0.0.1:5037.
+github_runner_network_mode: default
+
 github_runner_github_host: "github.com"
 
 github_runner_persist_config: true

roles/github_runner/tasks/main.yml

@@ -10,10 +10,19 @@
     device_cgroup_rules: "{{ ['c 189:* rmw'] if (github_runner_java and github_runner_java_mount_usb) else omit }}"
     volumes: "{{ runner_volumes }}"
     restart_policy: unless-stopped
-    ports: "{{ [github_runner_adb_port | string ~ ':5037'] if (github_runner_android and github_runner_android_expose_adb_ports) else omit }}"
+    network_mode: "{{ github_runner_network_mode }}"
+    ports: "{{ runner_ports }}"
     env: "{{ runner_env }}"
     env_file: "{{ github_runner_env_filename if github_runner_env_file else omit }}"
   vars:
+    # ports: is invalid together with network_mode: host, so omit it in host mode.
+    runner_ports: >-
+      {{
+        [github_runner_adb_port | string ~ ':5037']
+        if (github_runner_android and github_runner_android_expose_adb_ports
+            and github_runner_network_mode != 'host')
+        else omit
+      }}
     runner_volumes: >-
       {{
         ['/var/run/docker.sock:/var/run/docker.sock'] +