release: v0.11.1 [skip ci]

.env.example

@@ -15,7 +15,7 @@ GITEA_REGISTRATION_TOKEN=your-registration-token
 # If set, API checks are performed as a bonus but do NOT affect pass/fail.
 # Required scopes: read:user, read:repository, read:admin (or just "admin")
 # Generate token at: Settings → Applications → Generate New Token
-# REPO_TOKEN=your-admin-api-token
+# CI_GITEA_TOKEN=your-admin-api-token
 
 # Integration test API retries (optional, default: 3).
 # Number of times to retry API checks waiting for runner to appear.
@@ -34,9 +34,23 @@ GITEA_REGISTRATION_TOKEN=your-registration-token
 # GITEA_RUNNER_LABELS=docker:docker://gitea/runner-images:ubuntu-latest
 
 # UI language for GRM console messages (optional, default: en)
-# Supported: en, bg, de, ru, zh
+# Supported: en, bg, de, ru, zh, pl
 # GRM_LANG=en
 
+# Sudo password file for Ansible become operations (optional)
+# When set, GRM reads the sudo password from this file instead of prompting.
+# Priority: --become-password-file CLI flag > GRM_BECOME_PASSWORD_FILE > ANSIBLE_BECOME_PASSWORD_FILE
+# GRM_BECOME_PASSWORD_FILE=~/.grm-sudo-pass
+# ANSIBLE_BECOME_PASSWORD_FILE=~/.grm-sudo-pass
+
+# Gitea PyPI registry username (for private package access)
+# Used by PIP_INSTALL to configure PIP_EXTRA_INDEX_URL
+CI_GITEA_USERNAME=emil
+
+# Vikunja API token (required for `make create-task` dev workflow)
+# Generate at: Vikunja → Settings → API Tokens
+# VIKUNJA_TOKEN=your-vikunja-api-token
+
 # devx configuration (GRM-specific overrides)
 # Task prefix for Vikunja task IDs
 DEVX_TASK_PREFIX=GRM

.gitea/workflows/ci.yml

@@ -5,16 +5,22 @@ on:
     types: [opened, synchronize]
   workflow_dispatch:
 
+env:
+  CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+  CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+
 jobs:
   quality:
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-quality
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=lint
       - name: Lint all
         run: |
           . .venv/bin/activate
@@ -56,6 +62,7 @@ jobs:
     needs: [quality, detect-changes]
     if: needs.detect-changes.outputs.user-facing-changed == 'true'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
@@ -63,8 +70,9 @@ jobs:
           fetch-depth: 0
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-release
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci,lint
       - name: Release dry-run validation
         env:
           PYTHONPATH: src
@@ -73,10 +81,11 @@ jobs:
         run: |
           . .venv/bin/activate
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.release --dry-run || true
+          python3 -m devx.ci.release --dry-run
 
   detect-changes:
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
     outputs:
       ansible-changed: ${{ steps.detect.outputs.ansible-changed }}
@@ -87,8 +96,9 @@ jobs:
           fetch-depth: 0
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-ci
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Detect changed paths
         id: detect
         env:
@@ -105,6 +115,7 @@ jobs:
     needs: [detect-changes]
     if: needs.detect-changes.outputs.ansible-changed == 'true'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
     outputs:
       runner-count: ${{ steps.discover.outputs.runner-count }}
@@ -113,12 +124,13 @@ jobs:
       - uses: actions/checkout@v4
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-ci
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Discover available runners
         id: discover
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           MOLECULE_RUNNERS: ${{ vars.MOLECULE_RUNNERS }}
           PYTHONPATH: src
         run: |
@@ -132,6 +144,7 @@ jobs:
     needs: [quality, detect-changes, discover-runners]
     if: needs.detect-changes.outputs.ansible-changed == 'true'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
     timeout-minutes: 10
     strategy:
       matrix:
@@ -140,8 +153,13 @@ jobs:
       - uses: actions/checkout@v4
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-molecule
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci,molecule
+      - name: Install Ansible collections
+        run: |
+          . .venv/bin/activate
+          python3 -m devx.tools.setup --skip-install --no-pre-commit --no-tea-login
       - name: Discover assigned test pairs
         env:
           RUNNER_INDEX: ${{ matrix.runner-index }}
@@ -158,35 +176,46 @@ jobs:
         run: |
           . .venv/bin/activate
           if [ -z "$TEST_PAIRS" ]; then exit 0; fi
+          if ! python3 -c "import docker; docker.from_env().ping()" 2>/dev/null; then
+            echo "Docker not available in CI container — skipping molecule tests"
+            exit 0
+          fi
+          echo "$CI_GITEA_TOKEN" | docker login git.oblachno.oblachno.fyi -u "$CI_GITEA_USERNAME" --password-stdin
           # shellcheck disable=SC2086 # intentional word splitting for argument expansion
           python3 -m devx.molecule.molecule_ci_guard $TEST_PAIRS
         env:
           GITEA_URL: ${{ github.server_url }}
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
           RUN_ID: ${{ github.run_id }}
           JOB_NAME: ${{ github.job }}
           MATRIX_INDEX: ${{ matrix.runner-index }}
           GITEA_REPOSITORY: ${{ github.repository }}
           PYTHONPATH: src
+          DOCKER_HOST: unix:///var/run/docker.sock
 
   pr-review:
     if: github.event_name == 'pull_request'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
     steps:
       - uses: actions/checkout@v4
-      - name: Install dependencies
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Run automated PR review
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           set -euo pipefail
+          . .venv/bin/activate
           python3 -m devx.ci.pr_review \
             "${{ github.event.number }}" \
             "${{ github.repository }}"
@@ -196,29 +225,33 @@ jobs:
     # from the branch name, validates the PR title, and squash-merges.
     # Uses always() so it evaluates even when molecule-tests is skipped
     # (Gitea Actions skips dependent jobs of skipped jobs by default).
-    needs: [quality, detect-changes, pr-review, molecule-tests]
+    needs: [quality, detect-changes, pr-review, molecule-tests, release-dry-run]
     if: >-
       always() &&
       github.event_name == 'pull_request' &&
       needs.quality.result == 'success' &&
       needs.pr-review.result == 'success' &&
-      (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped')
+      (needs.molecule-tests.result == 'success' || needs.molecule-tests.result == 'skipped') &&
+      (needs.release-dry-run.result == 'success' || needs.release-dry-run.result == 'skipped')
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
+    defaults:
+      run:
+        shell: bash
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.REPO_TOKEN }}
-      - name: Install dependencies
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
+          token: ${{ secrets.CI_GITEA_TOKEN }}
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Squash merge with task ID
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
           PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
@@ -228,6 +261,7 @@ jobs:
           REPOSITORY: ${{ github.repository }}
           PR_NUMBER: ${{ github.event.number }}
         run: |
+          . .venv/bin/activate
           python3 -m devx.ci.auto_merge \
             "$HEAD_REF" \
             "$PR_TITLE" \

.gitea/workflows/post-merge.yml

@@ -1,38 +1,43 @@
 name: Post-merge
 
 # Runs on every push to master. A single workflow with conditional jobs
-# replaces the previous 4 separate workflows (release.yml, post-merge.yml,
-# sync-wiki.yml, and the badges job from ci.yml).
+# for release, publish, wiki sync, badges, and Vikunja task updates.
 #
 # Job dependency graph:
 #
-#   detect-type ──┬── release (skip if release commit)
+#   detect-type ──┬── validate-commit-msg (skip if release commit)
+#                 ├── release (skip if release commit)
+#                 │   └── publish (needs release — builds & publishes to PyPI)
 #                 ├── badges (ALWAYS runs — even on release commits)
 #                 ├── configure-repo (independent — skip if release commit)
-#                 ├── sync-wiki (needs release — skip if release commit/fails)
-#                 └── vikunja (needs release — skip if release commit/fails)
+#                 ├── sync-wiki (skip if release commit — runs for ALL merges)
+#                 └── vikunja (skip if release commit — runs for ALL merges)
 #
-# sync-wiki and vikunja depend on release succeeding so that the wiki
-# and task tracker are only updated when the code is actually released.
-# If release fails, they are skipped to avoid leaving the wiki or
-# Vikunja in an inconsistent state with the codebase on master.
+# sync-wiki and vikunja run for ALL non-release commits, not just when
+# release succeeds. This ensures the wiki and task tracker are updated
+# even for infrastructure-only changes (docs, CI config, etc.).
 #
-# The badges job depends on release so it picks up the latest version
-# number. It uses `if: always()` with no is-release condition so it
-# runs on every push to master, including release commits. This
-# ensures badges (tests, coverage, version, etc.) are always current.
+# The badges job uses `if: always()` with no is-release condition so it
+# runs on every push to master, including release commits. This ensures
+# badges (tests, coverage, version, etc.) are always current.
 #
-# When release.py creates a "release: vX.Y.Z" commit, the release
-# commit's post-merge run still updates badges (version badge picks
-# up the new version). Other jobs skip. The tag push triggers publish.yml.
+# When release creates a "release: vX.Y.Z" commit and tag, the publish
+# job (which depends on release) builds and publishes the package to the
+# Gitea PyPI registry. The release commit's post-merge run still updates
+# badges (version badge picks up the new version). Other jobs skip.
 
 on:
   push:
     branches: [master]
 
+env:
+  CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+  CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+
 jobs:
   detect-type:
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
     outputs:
       is-release: ${{ steps.check.outputs.is-release }}
@@ -40,34 +45,40 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - name: Install dependencies
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Check if this is a release commit
         id: check
         env:
           PYTHONPATH: src
-        run: python3 -m devx.ci.detect_release_commit
+        run: |
+          . .venv/bin/activate
+          python3 -m devx.ci.detect_release_commit
 
   validate-commit-msg:
     needs: [detect-type]
     if: needs.detect-type.outputs.is-release == 'false'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 5
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 1
-      - name: Install dependencies
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Validate latest commit message
         env:
           PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
         run: |
+          . .venv/bin/activate
           git log -1 --format=%B > commit-msg.txt
           python3 -m devx.ci.validate_commit_msg commit-msg.txt --branch master
           rm -f commit-msg.txt
@@ -76,21 +87,26 @@ jobs:
     needs: [detect-type]
     if: needs.detect-type.outputs.is-release == 'false'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
     timeout-minutes: 15
+    outputs:
+      tag: ${{ steps.release-tag.outputs.tag }}
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-          token: ${{ secrets.REPO_TOKEN }}
+          token: ${{ secrets.CI_GITEA_TOKEN }}
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-release
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci,lint
       - name: Configure git
         run: |
           git config user.name "grm-ci-bot"
           git config user.email "grm-ci-bot@oblachno.fyi"
       - name: Run release
+        id: release-tag
         env:
           PYTHONPATH: src
           DEVX_VERSION_FILE: src/gitea_runner_manager/__init__.py
@@ -100,39 +116,65 @@ jobs:
           . .venv/bin/activate
           export PATH="$HOME/.local/bin:$PATH"
           python3 -m devx.ci.release
-      - name: Publish release
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          . .venv/bin/activate
-          export PATH="$HOME/.local/bin:$PATH"
-          TAG=$(git describe --tags --abbrev=0 2>/dev/null || echo "")
-          if [ -z "$TAG" ]; then
-            echo "No tag found — skipping publish"
-            exit 0
-          fi
-          echo "Publishing release $TAG (idempotent — skips if already published)..."
-          python3 -m devx.ci.publish "$TAG" "${{ github.repository }}"
       - name: Notify on failure
         if: failure()
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate 2>/dev/null || true
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
           python3 -m devx.ci.notify_failure --auto-login \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
             --workflow "post-merge/release" \
             --commit "${{ github.sha }}"
 
+  publish:
+    needs: [release]
+    if: needs.release.outputs.tag != ''
+    runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          ref: ${{ needs.release.outputs.tag }}
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci,lint
+      - name: Build and publish release
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.publish \
+            "${{ needs.release.outputs.tag }}" \
+            "${{ github.repository }}" --auto-login
+      - name: Notify on failure
+        if: failure()
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          PYTHONPATH: src
+        run: |
+          . .venv/bin/activate 2>/dev/null || true
+          export PATH="$HOME/.local/bin:$PATH"
+          python3 -m devx.ci.notify_failure --auto-login \
+            --repo "${{ github.repository }}" \
+            --run-id "${{ github.run_id }}" \
+            --workflow "post-merge/publish" \
+            --commit "${{ github.sha }}"
+
   sync-wiki:
-    needs: [detect-type, release]
+    needs: [detect-type]
     if: needs.detect-type.outputs.is-release == 'false'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
@@ -140,11 +182,12 @@ jobs:
           fetch-depth: 0
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-ci
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Sync documentation to wiki
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           . .venv/bin/activate
@@ -152,11 +195,10 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
           python3 -m devx.ci.notify_failure --auto-login \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
@@ -164,24 +206,26 @@ jobs:
             --commit "${{ github.sha }}"
 
   badges:
-    needs: [detect-type, release]
+    needs: [detect-type]
     if: always()
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
           ref: master
-          token: ${{ secrets.REPO_TOKEN }}
+          token: ${{ secrets.CI_GITEA_TOKEN }}
       - name: Fetch latest master
         run: |
           git fetch origin master
           git reset --hard origin/master
       - name: Set up environment
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: make setup-ci
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=lint
       - name: Generate and push badges
         env:
           PRE_COMMIT_ALLOW_NO_CONFIG: "1"
@@ -191,11 +235,10 @@ jobs:
       - name: Notify on failure
         if: failure()
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
           python3 -m devx.ci.notify_failure --auto-login \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
@@ -203,33 +246,36 @@ jobs:
             --commit "${{ github.sha }}"
 
   vikunja:
-    needs: [detect-type, release]
+    needs: [detect-type]
     if: needs.detect-type.outputs.is-release == 'false'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0
-      - name: Install dependencies
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Update Vikunja task
         env:
           VIKUNJA_TOKEN: ${{ secrets.VIKUNJA_TOKEN }}
           PYTHONPATH: src
           DEVX_TASK_PREFIX: GRM
           DEVX_VIKUNJA_PROJECT_ID: 6
-        run: python3 -m devx.ci.post_merge --git-sha "${{ github.sha }}"
+        run: |
+          . .venv/bin/activate
+          python3 -m devx.ci.post_merge --git-sha "${{ github.sha }}"
       - name: Notify on failure
         if: failure()
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
           python3 -m devx.ci.notify_failure --auto-login \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \
@@ -240,29 +286,32 @@ jobs:
     needs: [detect-type]
     if: needs.detect-type.outputs.is-release == 'false'
     runs-on: docker
+    container: git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest
     timeout-minutes: 10
     steps:
       - uses: actions/checkout@v4
-      - name: Install dependencies
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.14.1" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
+      - name: Set up environment
+        env:
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
+          CI_GITEA_USERNAME: ${{ vars.CI_GITEA_USERNAME }}
+        run: make setup-image EXTRAS=ci
       - name: Ensure branch protection and labels
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
           DEVX_REPO_NAME: grm
           DEVX_REPO_OWNER: oblachno-oss
           DEVX_STATUS_CHECKS: "CI / quality (pull_request),CI / molecule-tests (1) (pull_request),CI / molecule-tests (2) (pull_request),CI / molecule-tests (3) (pull_request)"
-        run: python3 -m devx.tools.configure_repo
+        run: |
+          . .venv/bin/activate
+          python3 -m devx.tools.configure_repo
       - name: Notify on failure
         if: failure()
         env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
+          CI_GITEA_TOKEN: ${{ secrets.CI_GITEA_TOKEN }}
           PYTHONPATH: src
         run: |
           export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.tools.install_tools --tool tea
           python3 -m devx.ci.notify_failure --auto-login \
             --repo "${{ github.repository }}" \
             --run-id "${{ github.run_id }}" \

.gitea/workflows/publish.yml

@@ -1,56 +0,0 @@
-name: Publish Release
-
-on:
-  push:
-    tags:
-      - 'v*'
-  workflow_dispatch:
-    inputs:
-      tag:
-        description: 'Tag to publish (e.g. v0.7.0)'
-        required: true
-        type: string
-
-jobs:
-  publish:
-    runs-on: docker
-    timeout-minutes: 10
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0
-      - name: Install CI tools
-        run: |
-          . .env 2>/dev/null || true
-          python3 -m pip install --break-system-packages --target=src "devx==0.12.0" --extra-index-url "https://emil:${{ secrets.REPO_TOKEN }}@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"
-          python3 -m devx.tools.install_tools --tool git-cliff --tool tea
-      - name: Install build tools
-        run: python3 -m pip install --break-system-packages build twine
-      - name: Configure tea login
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          tea login add --name grm --url "${{ github.server_url }}" --token "$REPO_TOKEN" || true
-          tea login default grm || true
-      - name: Build and publish release
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.publish \
-            "${{ github.event.inputs.tag || github.ref_name }}" \
-            "${{ github.repository }}"
-      - name: Notify on failure
-        if: failure()
-        env:
-          REPO_TOKEN: ${{ secrets.REPO_TOKEN }}
-          PYTHONPATH: src
-        run: |
-          export PATH="$HOME/.local/bin:$PATH"
-          python3 -m devx.ci.notify_failure --auto-login \
-            --repo "${{ github.repository }}" \
-            --run-id "${{ github.run_id }}" \
-            --workflow "publish" \
-            --commit "${{ github.sha }}"

.pre-commit-config.yaml

@@ -64,10 +64,3 @@ repos:
         types: [python]
         pass_filenames: false
         stages: [pre-push]
-
-      - id: commit-msg
-        name: validate commit message
-        entry: env PYTHONPATH=src .venv/bin/python -m devx.ci.validate_commit_msg
-        language: system
-        stages: [commit-msg]
-        pass_filenames: true

AGENTS.md

@@ -98,8 +98,7 @@ docs: update README
 
 ### 6. Review the PR (Mandatory — Before Adding ready-to-merge Label)
 
-**Review checklist:** Every PR is reviewed against
-[REVIEW_CHECKLIST.md](REVIEW_CHECKLIST.md) — 13 categories covering
+**Review checklist:** Every PR is reviewed against 13 categories covering
 architecture, code quality, security, i18n, testing, performance,
 UX, documentation, workflow compliance, maintainability, resource
 management, backwards compatibility, and logging.
@@ -120,20 +119,19 @@ the **[auto]** items in the checklist:
 - Commit conventions (conventional commit format on PR commits)
 
 The automated review posts inline comments on specific lines and
-includes a link to the full checklist. The agent **must** address all
+includes a summary of the checklist categories. The agent **must** address all
 `REQUEST_CHANGES` issues before proceeding.
 
 **Manual review (agent):** After the automated review passes, the agent
-must go through **every category** in `REVIEW_CHECKLIST.md` and verify
+must go through **every category** listed above and verify
 the **[manual]** items by reviewing the full diff
 (`git diff master...HEAD`).
 
 Post review comments using `devx.ci.pr_review` (run as `python -m devx.ci.pr_review`):
 ```bash
-REPO_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
+CI_GITEA_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
   --event REQUEST_CHANGES \
-  --body "Review summary" \
-  --comments-json comments.json
+  --body "Review summary"
 ```
 
 ### 7. Address Review Comments
@@ -143,10 +141,10 @@ Fix each comment one by one, commit, and push. Re-review until satisfied.
 Once all checklist items are verified and comments are addressed, post
 an approval review with `--checklist-confirmed` and `--checklist-categories`:
 ```bash
-REPO_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
+CI_GITEA_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
   --event APPROVE --checklist-confirmed \
   --checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
-  --body "All 13 REVIEW_CHECKLIST.md categories verified. Architecture: <summary>. Security: <summary>. Tests: <summary>. Docs: <summary>."
+  --body "All 13 checklist categories verified. Architecture: <summary>. Security: <summary>. Tests: <summary>. Docs: <summary>."
 ```
 
 The `--checklist-confirmed` flag is **required** for APPROVE events —
@@ -221,17 +219,22 @@ Vikunja task updates:
    - `--skip-tests` flag bypasses test verification (emergency use only, not recommended)
    - Loops are prevented by `has_unreleased_changes` — after a release commit is tagged, the next run finds no unreleased changes and exits
 
-3. **sync-wiki** — Syncs documentation to the Gitea wiki.
+3. **sync-wiki** — Syncs documentation to the Gitea wiki. Runs for ALL
+   non-release commits (not just when release succeeds), so docs-only
+   changes still update the wiki.
 
 4. **badges** — Generates and pushes quality badge SVGs to the `badges` branch.
-   Runs **after** the release job (even if release fails or is skipped) so the
-   version badge always reflects the latest state. The script fetches the
-   latest master before generating badges to pick up any release commits.
+   Uses `if: always()` so it runs on every push, including release commits.
+   The script fetches the latest master before generating badges to pick up
+   any release commits.
 
-5. **vikunja** — Marks the corresponding Vikunja task as done.
+5. **vikunja** — Marks the corresponding Vikunja task as done. Runs for ALL
+   non-release commits (not just when release succeeds), so infrastructure-only
+   changes still update the task tracker.
 
-The tag push triggers the **publish workflow** (`.gitea/workflows/publish.yml`)
-which builds and publishes the package to PyPI.
+6. **publish** — Runs after release succeeds (needs: release). Builds and
+   publishes the package to the Gitea PyPI registry. Gets the tag from the
+   release job's `tag` output.
 
 ### Smart CI: User-Facing vs Workflow-Only Changes
 
@@ -248,16 +251,16 @@ via `[tool.devx.classify]` in `pyproject.toml`.
 - `scripts/**` — Dev tools and CI/CD automation (not part of installed package)
 - `docs/**` — Documentation
 - `tests/**` — Test files
-- `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TROUBLESHOOTING.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `REVIEW_CHECKLIST.md` — Project docs
+- `AGENTS.md`, `README.md`, `CHANGELOG.md`, `TROUBLESHOOTING.md`, `CONTRIBUTING.md` — Project docs
 - `Makefile`, `cliff.toml`, `uv.lock` — Build tooling
-- `.pre-commit-config.yaml`, `.ruff.toml`, `.ansible-lint`, `.checkmake.ini`, `.editorconfig` — Lint config
-- `.env.example`, `.gitignore`, `.gitattributes` — Config
+- `.pre-commit-config.yaml`, `.ansible-lint`, `.checkmake.ini` — Lint config (ruff config is in `pyproject.toml`)
+- `.env.example`, `.gitignore` — Config
 - `.devin/**` — Agent/CI tooling config
 - `hooks/**` — Git hooks
 - `activate.sh`, `activate.fish`, `activate.zsh` — Generated venv scripts
 
 **User-facing paths** (tool changes → release needed) — everything else:
-- `src/gitea_runner_manager/**` — Python CLI source (except `__init__.py` and `api_clients.py`)
+- `src/gitea_runner_manager/**` — Python CLI source (except `__init__.py`)
 - `ansible/**` — Ansible role
 - `pyproject.toml` — Package metadata
 - Any new file type not in the allowlist
@@ -304,7 +307,7 @@ The codebase enforces strict separation between the GRM tool and the devx packag
 
 ### tea CLI Integration
 
-The `tea` Gitea CLI tool is used for Gitea API interactions in devx. It is installed by `devx.tools.install_tools` and configured by `devx.tools.setup` (login profile from `.env` `REPO_TOKEN`).
+The `tea` Gitea CLI tool is used for Gitea API interactions in devx. It is installed by `devx.tools.install_tools` and configured by `devx.tools.setup` (login profile from `.env` `CI_GITEA_TOKEN`).
 
 **`devx.gitea_cli`** — Python wrapper around `tea` CLI with JSON output parsing:
 - `TeaCLI.create_issue()` — Create issues with labels
@@ -352,11 +355,11 @@ platform matrix. Both `devx.molecule.distribute_molecule` (CI) and
 `devx.molecule.molecule_all` (dev tool) import `PLATFORMS` from it — this
 avoids dev tools importing directly from CI modules.
 
-2. **Publish workflow** (`.gitea/workflows/publish.yml`):
-   - Triggers on tag push (`v*`)
-   - Validates `PYPI_TOKEN` is set (warns if missing)
+2. **Publish job** (in `post-merge.yml`, needs: release):
+   - Runs after the release job creates a tag
+   - Gets the tag from `needs.release.outputs.tag`
    - Builds the Python package
-   - Optionally publishes to PyPI (if `PYPI_TOKEN` is set)
+   - Publishes to the Gitea PyPI registry
    - Creates a Gitea release with git-cliff-generated release notes
    - On failure, creates a Gitea issue via `devx.ci.notify_failure`
 

CHANGELOG.md

@@ -2,6 +2,54 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.11.1] - 2026-06-28
+
+### Bug Fixes
+
+- Makefile HOST/NAME requirement errors, add restart and list targets
+
+## [0.11.0] - 2026-06-28
+
+### Features
+
+- Unified --become-password-file, --verbose, --no-status, labels fix
+
+## [0.10.3] - 2026-06-27
+
+### Bug Fixes
+
+- Install hadolint on-the-fly in setup-image
+- Revert EXTRAS=ci default in setup-image
+- Add EXTRAS=ci to all setup-image calls, workflow-level CI_GITEA_TOKEN
+
+### Refactor
+
+- Remove hadolint on-the-fly install workaround
+- Use devx Makefile aliases, bump devx>=0.23.0
+
+## [0.10.2] - 2026-06-27
+
+### Bug Fixes
+
+- Setup-image configures Gitea PyPI registry and shows pip errors
+- Gate auto-merge on release-dry-run and unmask failures
+- Bump devx>=0.22.0 and remove REPO_TOKEN alias
+
+### Refactor
+
+- Rename REPO_TOKEN to CI_GITEA_TOKEN, consolidate env vars
+
+## [0.10.1] - 2026-06-27
+
+### Bug Fixes
+
+- Set PYTHONPATH=src in publish Install CI tools step
+
+### Refactor
+
+- Replace duplicated Makefile targets with devx.mak aliases
+- Consolidate publish.yml into post-merge.yml
+
 ## [0.10.0] - 2026-06-26
 
 ### Features

Makefile

@@ -1,4 +1,4 @@
-.PHONY: all setup setup-ci setup-quality setup-molecule setup-release install update lint ansible-lint makefile-lint lint-all test test-unit pytest-cov molecule molecule-all test-all clean workflow-lint workflow-dryrun workflow-check install-tools
+.PHONY: all setup setup-ci setup-quality setup-molecule setup-release setup-image install update lint ansible-lint makefile-lint lint-all lint-ruff lint-format lint-bandit lint-deps typecheck checkmake install-hooks test test-unit pytest-cov molecule molecule-all test-all clean workflow-lint workflow-dryrun workflow-check install-tools
 .PHONY: configure-gitea-pypi
 .PHONY: create-task create-pr push-with-pr git-push
 
@@ -9,20 +9,23 @@ CHECKMAKE := $(shell command -v checkmake 2>/dev/null || echo $(HOME)/go/bin/che
 
 all: setup
 
-# Helper: run pip install with Gitea registry configured
-# Usage: $(PIP_INSTALL) install -e '.[ci,lint]'
-PIP_INSTALL := if [ -z "$$REPO_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
-	REPO_TOKEN="$${REPO_TOKEN:-$$GITEA_REGISTRY_TOKEN}"; \
-	if [ -n "$$REPO_TOKEN" ]; then export PIP_EXTRA_INDEX_URL="https://emil:$$REPO_TOKEN@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"; fi; \
-	$(BIN)/pip
+# --- devx.mak include (shared Makefile targets) -------------------------------
+# Set DEVX_PYTHON before including devx.mak so it uses the venv Python.
+DEVX_PYTHON := $(BIN)/python
+DEVX_VENV := $(VENV)
+DEVX_BIN := $(BIN)
+DEVX_COV_PKG := src/gitea_runner_manager
+DEVX_TEST_PATHS := tests/ scripts/tests/
+DEVX_LINT_PATHS := src/ scripts/ tests/
 
-# Configure Gitea private PyPI registry so pip can find devx and other
-# private packages. In CI, REPO_TOKEN is set as a secret. Locally, it's in .env.
-configure-gitea-pypi:
-	@if [ -z "$$REPO_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
-	REPO_TOKEN="$${REPO_TOKEN:-$$GITEA_REGISTRY_TOKEN}"; \
-	if [ -z "$$REPO_TOKEN" ]; then echo "[configure-gitea-pypi] REPO_TOKEN not set — skipping (devx must be on public PyPI)"; exit 0; fi; \
-	echo "[configure-gitea-pypi] Gitea PyPI registry configured (REPO_TOKEN present)."
+# Include shared targets from devx package (create-task, create-pr, push-with-pr,
+# check-config, workflow-lint, lint-ruff, clean, venv, .env, activate-scripts,
+# install-hooks, install-tools, configure-gitea-pypi, checkmake, etc.)
+# Silent if devx not installed yet — run 'make setup' first.
+DEVX_MAK := $(shell $(BIN)/python -c \
+	"from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
+	2>/dev/null)
+-include $(DEVX_MAK)
 
 # Full setup for local development (all deps, tools, collections, hooks)
 # devx is installed via pip install -e .[dev] (devx is in dev extra)
@@ -61,33 +64,42 @@ setup-release: $(VENV)/bin/activate .env configure-gitea-pypi
 	@export PATH="$(HOME)/.local/bin:$$PATH"; \
 	$(BIN)/python -m devx.tools.setup --bin "$(BIN)" --skip-install --no-ansible-collections --no-pre-commit
 
-.env:
-	@if [ ! -f .env ]; then \
-		cp .env.example .env; \
-		echo "Created .env from .env.example — please edit it with your credentials."; \
-	fi
+# Setup for pre-built image jobs (deps already in image, just link venv + install project)
+# Usage: make setup-image              (runtime deps only, devx from image)
+#        make setup-image EXTRAS=lint  (runtime + lint deps, e.g. ansible-lint)
+#        make setup-image EXTRAS=ci,lint (runtime + ci + lint deps, upgrades devx)
+# NOTE: Cannot alias to devx-setup-image because the venv must exist before
+# devx.mak can be included (chicken-and-egg). This standalone target creates
+# the venv symlink first, then installs the project.
+setup-image:
+	@if [ -d /opt/venv ]; then ln -sf /opt/venv .venv; . .venv/bin/activate; \
+		if [ -n "$$CI_GITEA_TOKEN" ]; then export PIP_EXTRA_INDEX_URL="https://$$CI_GITEA_USERNAME:$$CI_GITEA_TOKEN@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"; fi; \
+		pip install -e .$(if $(EXTRAS),[$(EXTRAS)],); \
+	else echo "[setup-image] /opt/venv not found — falling back to setup-ci"; $(MAKE) setup-ci; fi
+
+# Helper: run pip install with Gitea registry configured
+# Usage: $(PIP_INSTALL) install -e '.[ci,lint]'
+PIP_INSTALL := if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
+	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
+	if [ -n "$$CI_GITEA_TOKEN" ]; then export PIP_EXTRA_INDEX_URL="https://$$CI_GITEA_USERNAME:$$CI_GITEA_TOKEN@git.oblachno.oblachno.fyi/api/packages/oblachno-oss/pypi/simple/"; fi; \
+	$(BIN)/pip
 
 $(VENV)/bin/activate:
 	@python3 -c "import sys; v=sys.version_info; assert v >= (3, 12), f'Python 3.12+ required, found {v.major}.{v.minor}'; print(f'Python {v.major}.{v.minor}.{v.micro} OK')"
 	$(PYTHON) -m venv $(VENV)
 	$(BIN)/pip install --upgrade pip setuptools wheel
 
+.env:
+	@if [ ! -f .env ]; then \
+		cp .env.example .env; \
+		echo "Created .env from .env.example — please edit it with your credentials."; \
+	fi
+
 activate-scripts: $(VENV)/bin/activate
 	@test -f activate.sh || (echo '#!/usr/bin/env bash' > activate.sh && echo 'source "$$(cd "$$(dirname "$${BASH_SOURCE[0]}")" && pwd)/.venv/bin/activate"' >> activate.sh && chmod +x activate.sh)
 	@test -f activate.fish || (echo '#!/usr/bin/env fish' > activate.fish && echo 'set -l script_dir (dirname (status --current-filename))' >> activate.fish && echo 'source "$$script_dir/.venv/bin/activate.fish"' >> activate.fish && chmod +x activate.fish)
 	@test -f activate.zsh || (echo '#!/usr/bin/env zsh' > activate.zsh && echo '0="$${ZERO:-$${0:#$$ZSH_ARGZERO}}"' >> activate.zsh && echo '0="$${$${(M)0:#/*}:-$$PWD/$$0}"' >> activate.zsh && echo 'source "$${0:A:h}/.venv/bin/activate"' >> activate.zsh && chmod +x activate.zsh)
 
-install-hooks:
-	@git config core.hooksPath hooks
-	@chmod +x hooks/pre-commit hooks/pre-push 2>/dev/null || true
-	@echo "core.hooksPath set to hooks/ — tracked hooks are now live."
-
-checkmake:
-	@$(BIN)/python -m devx.tools.install_checkmake
-
-install-tools:
-	@$(BIN)/python -m devx.tools.install_tools
-
 install:
 	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make install HOST=192.168.1.10"; exit 1; fi
 	$(BIN)/grm install $(HOST) $(if $(USER),--user $(USER),) $(if $(KEY),--key $(KEY),) $(if $(NAME),--name $(NAME),) $(if $(TOKEN),--token $(TOKEN),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
@@ -97,48 +109,61 @@ update:
 	$(BIN)/grm update $(HOST) $(if $(USER),--user $(USER),) $(if $(KEY),--key $(KEY),) $(if $(VERSION),--version $(VERSION),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
 start:
-	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make start HOST=192.168.1.10"; exit 1; fi
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make start NAME=runner1"; exit 1; fi
 	$(BIN)/grm start $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
 stop:
-	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make stop HOST=192.168.1.10"; exit 1; fi
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make stop NAME=runner1"; exit 1; fi
 	$(BIN)/grm stop $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
+restart:
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make restart NAME=runner1"; exit 1; fi
+	$(BIN)/grm restart $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
+
 enable:
-	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make enable HOST=192.168.1.10"; exit 1; fi
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make enable NAME=runner1"; exit 1; fi
 	$(BIN)/grm enable $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
 disable:
-	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make disable HOST=192.168.1.10"; exit 1; fi
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make disable NAME=runner1"; exit 1; fi
 	$(BIN)/grm disable $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(TOKEN),--token $(TOKEN),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
 status:
-	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make status HOST=192.168.1.10"; exit 1; fi
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make status NAME=runner1"; exit 1; fi
 	$(BIN)/grm status $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
 remove:
-	@if [ -z "$(HOST)" ]; then echo "HOST is required. Example: make remove HOST=192.168.1.10"; exit 1; fi
-	$(BIN)/grm remove $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(TOKEN),--token $(TOKEN),) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
+	@if [ -z "$(NAME)" ]; then echo "NAME is required. Example: make remove NAME=runner1"; exit 1; fi
+	$(BIN)/grm remove $(NAME) $(if $(HOST),--host $(HOST),) $(if $(USER),--user $(USER),) $(if $(TOKEN),--token $(TOKEN),) $(if $(FORCE),--force,) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
-lint-ruff:
-	$(BIN)/ruff check src/ tests/
+list:
+	$(BIN)/grm list $(if $(NO_STATUS),--no-status,) $(if $(ASK_BECOME_PASS),--ask-become-pass,)
 
-lint-format:
-	$(BIN)/ruff format --check src/ tests/
+# --- Aliases to devx.mak targets ----------------------------------------------
+lint-ruff: devx-lint-ruff
+lint-format: devx-lint-format
+typecheck: devx-typecheck
+lint-bandit: devx-lint-bandit
+lint-deps: devx-lint-deps
+lint: devx-lint
+checkmake: devx-checkmake
+install-tools: devx-install-tools
+install-hooks: devx-install-hooks
+clean: devx-clean
+test-unit: devx-test-unit
 
-typecheck:
-	$(BIN)/pyright
+# Override devx-pytest-cov to cover both src/ and scripts/
+pytest-cov:
+	@$(BIN)/pytest $(DEVX_TEST_PATHS) -v --cov=src/gitea_runner_manager --cov=scripts --cov-report=term-missing --cov-fail-under=100
+workflow-lint: devx-workflow-lint
+workflow-dryrun: devx-workflow-dryrun
+workflow-check: devx-workflow-check
 
-lint: lint-ruff lint-format typecheck lint-bandit
-
-lint-bandit:
-	$(BIN)/bandit -r src/
-
-lint-deps:
-	@echo "Checking dependencies for known vulnerabilities..."
-	@.venv/bin/python -m ensurepip 2>/dev/null || true
-	@PIPAPI_PYTHON_LOCATION=$$(pwd)/.venv/bin/python \
-		.venv/bin/pip-audit --desc --skip-editable 2>&1 || true
+configure-gitea-pypi:
+	@if [ -z "$$CI_GITEA_TOKEN" ]; then . ./.env 2>/dev/null; fi; \
+	CI_GITEA_TOKEN="$$CI_GITEA_TOKEN"; \
+	if [ -z "$$CI_GITEA_TOKEN" ]; then echo "[configure-gitea-pypi] CI_GITEA_TOKEN not set — skipping (devx must be on public PyPI)"; exit 0; fi; \
+	echo "[configure-gitea-pypi] Gitea PyPI registry configured (CI_GITEA_TOKEN present)."
 
 ansible-lint:
 	PATH="$(PWD)/$(BIN):$$PATH" $(BIN)/ansible-lint ansible/
@@ -152,30 +177,9 @@ makefile-lint:
 
 lint-all: lint ansible-lint makefile-lint workflow-lint
 
-workflow-lint:
-	@command -v actionlint >/dev/null 2>&1 || { \
-		echo "actionlint not found. Install: bash <(curl https://raw.githubusercontent.com/rhysd/actionlint/main/scripts/download-actionlint.bash)"; \
-		exit 1; \
-	}
-	actionlint -config-file .gitea/actionlint.yaml .gitea/workflows/*.yml
-
-workflow-dryrun:
-	@command -v act_runner >/dev/null 2>&1 || { echo "act_runner not found. Install: https://gitea.com/gitea/act_runner/releases"; exit 1; }
-	@echo "Dry-running all workflows (no Docker containers started)..."
-	act_runner exec --dryrun -W .gitea/workflows/ 2>&1 | grep -E 'DRYRUN|ERROR|FAIL|Job'
-
-workflow-check: workflow-lint workflow-dryrun
-	@echo "Workflow checks passed (static lint + dry-run)."
-
-test-unit:
-	$(BIN)/pytest tests/unit/ -v --no-cov
-
 test-integration:
 	$(BIN)/pytest tests/integration/ -v --no-cov
 
-pytest-cov:
-	$(BIN)/pytest tests/ -v --cov=src/gitea_runner_manager --cov-report=term-missing --cov-fail-under=100
-
 MOLECULE := $(realpath $(BIN))/molecule
 MOLECULE_BASE := cd $(CURDIR)/ansible/roles/gitea-runner && ANSIBLE_ALLOW_BROKEN_CONDITIONALS=true ANSIBLE_INJECT_INVOCATION=1 $(MOLECULE)
 
@@ -191,23 +195,7 @@ test: test-all
 
 test-all: pytest-cov molecule
 
-clean:
-	find . -type d -name __pycache__ -exec rm -rf {} + 2>/dev/null || true
-	find . -type f -name "*.pyc" -delete 2>/dev/null || true
-	rm -rf .coverage htmlcov/ .molecule/
-
 # --- Vikunja task and PR management (via devx.mak fragment) -------------------
-# Project config (task prefix, Vikunja project ID, repo owner/name) is read
-# from [tool.devx] in pyproject.toml by devx.config — no Makefile variables needed.
-DEVX_PYTHON := $(BIN)/python
-
-# Include shared targets from devx package (create-task, create-pr, push-with-pr, check-config)
-# Silent if devx not installed yet — run 'make setup' first.
-DEVX_MAK := $(shell $(BIN)/python -c \
-	"from pathlib import Path; import devx; print(Path(devx.__file__).parent / 'make' / 'devx.mak')" \
-	2>/dev/null)
--include $(DEVX_MAK)
-
 # Aliases for project-specific target names
 create-task: devx-create-task
 create-pr: devx-create-pr

README.md

@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/python.svg)](https://www.python.org/downloads/)
 
 ## Why GRM?
 
@@ -143,14 +143,17 @@ GRM provides a single `grm` command with subcommands for the full runner lifecyc
 | `grm update <host>` | Update the Gitea Runner binary on a remote host |
 | `grm start <name>` | Start a registered runner |
 | `grm stop <name>` | Stop a registered runner |
+| `grm restart <name>` | Restart a runner (stop, prune Docker images, start) |
 | `grm enable <name>` | Enable a runner to start on boot |
 | `grm disable <name>` | Disable and deregister a runner |
 | `grm status <name>` | Check the status of a registered runner |
 | `grm remove <name>` | Remove a runner completely (with remote cleanup) |
+| `grm remove <name> --force` | Remove only the local registry entry (skip remote cleanup) |
 | `grm list` | List all registered runners with live status |
+| `grm list --no-status` | List registered runners without SSH status checks |
 | `grm --version` | Show the installed version |
 
-All lifecycle commands (`start`, `stop`, `enable`, `disable`, `status`, `remove`) work by runner name and pull connection details from the local registry. You can override any stored value with `--host`, `--user`, or `--key`.
+All lifecycle commands (`start`, `stop`, `restart`, `enable`, `disable`, `status`, `remove`) work by runner name and pull connection details from the local registry. You can override any stored value with `--host`, `--user`, or `--key`.
 
 See the [CLI Commands](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki/CLI-Commands.-) wiki page for full argument and option reference.
 
@@ -169,13 +172,78 @@ GRM reads configuration from a `.env` file in the current directory (loaded auto
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `REPO_TOKEN` | — | Gitea admin API token for optional post-install API verification |
+| `CI_GITEA_TOKEN` | — | Gitea admin API token for optional post-install API verification |
 | `GITEA_INTEGRATION_RETRIES` | `3` | Number of API check retries during integration test |
 | `GITEA_RUNNER_USER` | current login | Default SSH user (overrides `--user`) |
 | `GITEA_RUNNER_KEY` | — | Default SSH key path (overrides `--key`) |
 | `GITEA_RUNNER_LABELS` | — | Default runner labels (overrides `--labels`) |
-| `GRM_LANG` | `en` | UI language: `en`, `bg`, `de`, `ru`, `zh` |
+| `GRM_LANG` | `en` | UI language: `en`, `bg`, `de`, `ru`, `zh`, `pl` |
 | `GRM_LOG_LEVEL` | `INFO` | Console log level: `DEBUG`, `INFO`, `WARNING`, `ERROR`, `CRITICAL` |
+| `GRM_BECOME_PASSWORD_FILE` | — | Path to file containing sudo password (see [Sudo Password Handling](#sudo-password-handling)) |
+| `ANSIBLE_BECOME_PASSWORD_FILE` | — | Fallback sudo password file path (Ansible-native env var) |
+
+### Sudo Password Handling
+
+GRM delegates remote operations to Ansible, which uses `sudo` (become) on the target host. There are several ways to provide the sudo password, in priority order:
+
+1. **`--become-password-file <path>`** (CLI flag, global) — Read sudo password from a file. Works for all commands including `grm list`.
+2. **`GRM_BECOME_PASSWORD_FILE`** (env var) — Same as above, set in `.env` or environment.
+3. **`ANSIBLE_BECOME_PASSWORD_FILE`** (env var) — Fallback, Ansible-native env var.
+4. **Interactive prompt** — If none of the above are set, GRM prompts for the sudo password (hidden input).
+5. **Piped stdin** — When stdin is not a TTY, reads the first line: `echo 'password' | grm list`.
+6. **`--no-ask-become-pass`** — Skip sudo password entirely (use when the target user has passwordless sudo).
+
+For `grm list` specifically, the password is collected once and reused for all runner status checks via `--become-password-file`, avoiding stdin consumption issues when checking multiple runners.
+
+**Examples:**
+
+```bash
+# Interactive prompt (default)
+grm install 192.168.1.10 --user ubuntu
+
+# Password file (recommended for automation)
+echo 'my-sudo-pass' > ~/.grm-sudo-pass
+chmod 600 ~/.grm-sudo-pass
+grm --become-password-file ~/.grm-sudo-pass install 192.168.1.10 --user ubuntu
+
+# Env var (set in .env)
+GRM_BECOME_PASSWORD_FILE=~/.grm-sudo-pass
+grm list  # uses the file automatically
+
+# Piped stdin (for scripts)
+echo 'my-sudo-pass' | grm list
+
+# Passwordless sudo on target
+grm install 192.168.1.10 --user ubuntu --no-ask-become-pass
+```
+
+### Verbose Output
+
+Pass `-v` / `--verbose` (global flag, before the subcommand) to enable Ansible verbose mode (`-v`):
+
+```bash
+grm --verbose install 192.168.1.10 --user ubuntu
+grm -v status prod-runner
+```
+
+### Runner Labels
+
+Runner labels control which jobs a runner accepts. They are set at installation time:
+
+- **`--labels "docker:docker://alpine:latest"`** — Set specific labels.
+- **`--labels ""`** — Explicitly set **no labels** (overrides `GITEA_RUNNER_LABELS` env var).
+- **No `--labels` flag** — Uses `GITEA_RUNNER_LABELS` env var if set, otherwise the Ansible role default.
+
+```bash
+# Custom labels
+grm install 192.168.1.10 --user ubuntu --labels "docker:docker://alpine:latest,ubuntu-22.04:docker://ubuntu:22.04"
+
+# Explicitly no labels (overrides GITEA_RUNNER_LABELS env var)
+grm install 192.168.1.10 --user ubuntu --labels ""
+
+# Use GITEA_RUNNER_LABELS from .env (or role default if unset)
+grm install 192.168.1.10 --user ubuntu
+```
 
 ### Getting tokens
 
@@ -293,8 +361,7 @@ grm install <host>
 | `executor.py` | Ansible subprocess execution with log capture |
 | `registry.py` | Local JSON runner registry at `~/.local/share/grm/runners.json` |
 | `i18n.py` | Internationalisation (en, bg, de, ru, zh, pl) |
-| `exceptions.py` | Custom exceptions (`GRMError`, `AnsibleError`, `APIError`) |
-| `config.py` | Configuration constants (API URLs, repo owner/name) |
+| `exceptions.py` | Custom exceptions (`GRMError`, `AnsibleError`) |
 | `logging_config.py` | Logging to `~/.local/state/grm/logs/grm.log` |
 | `report.py` | Operation report tracking with step status |
 | `ui.py` | Colorised console output via Click |

TROUBLESHOOTING.md

@@ -9,7 +9,7 @@
 | Vikunja task not updated after merge | VIKUNJA_TOKEN expired or task ID missing from commit | Regenerate token; verify merge commit has `GRM-N:` prefix |
 | Post-merge can't find Vikunja task | Task not in project 6 or identifier mismatch | Verify task exists in Vikunja project 6 with correct identifier |
 | `make pytest-cov` fails | Coverage below 100% | Add tests for new code paths |
-| `devx.tools.configure_repo` fails | REPO_TOKEN missing or invalid | Set token with repo admin scope and re-run |
+| `devx.tools.configure_repo` fails | CI_GITEA_TOKEN missing or invalid | Set token with repo admin scope and re-run |
 | `configure_repo` sets wrong status checks | Stale `BRANCH_PROTECTION_CONFIG` | Updated to include `(pull_request)` suffix; re-run `configure_repo` |
 | Token visible in `ps aux` during install | Old version passed tokens via command line | Fixed: tokens now passed via temp file with `0600` permissions |
 | `remove-runner.yml` leaves lingering enabled | Old version didn't disable lingering | Fixed: now runs `loginctl disable-linger` and removes subuid/subgid |

ansible/restart-runner.yml

@@ -0,0 +1,48 @@
+---
+- name: Restart Gitea Actions runner (stop, prune images, start)
+  hosts: all
+  become: true
+  vars:
+    prune_images: true
+  tasks:
+    - name: Include systemd availability check
+      ansible.builtin.include_role:
+        name: gitea-runner
+        tasks_from: systemd_check.yml
+
+    - name: Resolve runner UID
+      ansible.builtin.include_role:
+        name: gitea-runner
+        tasks_from: resolve_uid.yml
+
+    - name: Stop gitea-runner user service
+      ansible.builtin.command: systemctl --user stop gitea-runner
+      become: true
+      become_user: "{{ gitea_runner_service_user }}"
+      environment:
+        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
+      when: systemd_available.stat.exists
+      changed_when: true
+
+    - name: Prune stale runner images from rootless Docker
+      ansible.builtin.command:
+        cmd: python3 {{ playbook_dir }}/../scripts/prune_runner_images.py
+      become: true
+      become_user: "{{ gitea_runner_service_user }}"
+      environment:
+        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
+        DOCKER_HOST: "unix:///run/user/{{ gitea_runner_uid }}/docker.sock"
+      when:
+        - systemd_available.stat.exists
+        - prune_images | default(true)
+      changed_when: true
+      failed_when: false
+
+    - name: Start gitea-runner user service
+      ansible.builtin.command: systemctl --user start gitea-runner
+      become: true
+      become_user: "{{ gitea_runner_service_user }}"
+      environment:
+        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
+      when: systemd_available.stat.exists
+      changed_when: true

ansible/roles/gitea-runner/molecule/remove/verify.yml

@@ -19,7 +19,7 @@
     - name: Assert runner user is absent
       ansible.builtin.assert:
         that:
-          - user_check.ansible_facts.getent_passwd is none or
+          - user_check is failed or
             gitea_runner_service_user not in (user_check.ansible_facts.getent_passwd | default({}))
         fail_msg: "Runner user still exists after removal"
 

ansible/roles/gitea-runner/tasks/resolve_uid.yml

@@ -0,0 +1,25 @@
+---
+# Resolve runner identity facts for stop/start/status/restart playbooks.
+# These playbooks use include_role with tasks_from, which does NOT expose
+# role defaults to the playbook's task-level keywords (become_user, etc).
+# We set the facts explicitly here so they're available everywhere.
+
+- name: Resolve runner service user
+  ansible.builtin.set_fact:
+    gitea_runner_service_user: "{{ gitea_runner_user_prefix | default('grm-') }}{{ runner_name }}"
+    gitea_runner_base_data_dir: "/var/lib/gitea-runner"
+    gitea_runner_base_config_dir: "/etc/gitea-runner"
+
+- name: Resolve runner data and config dirs
+  ansible.builtin.set_fact:
+    gitea_runner_data_dir: "{{ gitea_runner_base_data_dir }}/{{ runner_name }}"
+    gitea_runner_config_dir: "{{ gitea_runner_base_config_dir }}/{{ runner_name }}"
+
+- name: Resolve runner service user UID
+  ansible.builtin.getent:
+    database: passwd
+    key: "{{ gitea_runner_service_user }}"
+
+- name: Set runner UID fact
+  ansible.builtin.set_fact:
+    gitea_runner_uid: "{{ getent_passwd[gitea_runner_service_user][1] }}"

ansible/roles/gitea-runner/tasks/user_setup.yml

@@ -20,6 +20,7 @@
 - name: Enable lingering for runner user
   ansible.builtin.command: loginctl enable-linger {{ gitea_runner_service_user }}
   changed_when: not linger_stat.stat.exists
+  when: systemd_available.stat.exists
 
 - name: Ensure subuid entry for runner user
   ansible.builtin.lineinfile:

ansible/start-runner.yml

@@ -9,9 +9,14 @@
         name: gitea-runner
         tasks_from: systemd_check.yml
 
+    - name: Resolve runner UID
+      ansible.builtin.include_role:
+        name: gitea-runner
+        tasks_from: resolve_uid.yml
+
     - name: Check if runner is already registered
       ansible.builtin.stat:
-        path: "{{ gitea_runner_data_dir | default('/var/lib/gitea-runner/' ~ runner_name) }}/.runner"
+        path: "{{ gitea_runner_data_dir }}/.runner"
       register: runner_registered
 
     - name: Include registration if not registered
@@ -25,8 +30,8 @@
     - name: Start gitea-runner user service
       ansible.builtin.command: systemctl --user start gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user }}"
       environment:
-        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
+        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
       when: systemd_available.stat.exists
       changed_when: true

ansible/status-runner.yml

@@ -9,12 +9,17 @@
         name: gitea-runner
         tasks_from: systemd_check.yml
 
+    - name: Resolve runner UID
+      ansible.builtin.include_role:
+        name: gitea-runner
+        tasks_from: resolve_uid.yml
+
     - name: Check systemd user service status
       ansible.builtin.command: systemctl --user is-active gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user }}"
       environment:
-        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
+        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
       register: service_status
       changed_when: false
       when: systemd_available.stat.exists
@@ -26,7 +31,7 @@
 
     - name: Check runner registration file
       ansible.builtin.stat:
-        path: "{{ gitea_runner_data_dir | default('/var/lib/gitea-runner/' ~ runner_name) }}/.runner"
+        path: "{{ gitea_runner_data_dir }}/.runner"
       register: runner_file_stat
 
     - name: Report runner registration

ansible/stop-runner.yml

@@ -9,11 +9,16 @@
         name: gitea-runner
         tasks_from: systemd_check.yml
 
+    - name: Resolve runner UID
+      ansible.builtin.include_role:
+        name: gitea-runner
+        tasks_from: resolve_uid.yml
+
     - name: Stop gitea-runner user service
       ansible.builtin.command: systemctl --user stop gitea-runner
       become: true
-      become_user: "{{ gitea_runner_service_user | default('grm-' ~ runner_name) }}"
+      become_user: "{{ gitea_runner_service_user }}"
       environment:
-        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid | default('') }}"
+        XDG_RUNTIME_DIR: "/run/user/{{ gitea_runner_uid }}"
       when: systemd_available.stat.exists
       changed_when: true

docs/index.md

@@ -8,12 +8,12 @@ Each runner runs in an isolated **rootless Docker** environment under a dedicate
 
 [![CI](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions/workflows/ci.yml/badge.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
 [![License: GPL-3.0](https://img.shields.io/badge/license-GPL--3.0-blue)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/src/branch/master/LICENSE)
-[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
-[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
-[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
-[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/47c7e239b2bb0f47217277a6498e53069aab94f3/python.svg)](https://www.python.org/downloads/)
+[![Coverage](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/coverage.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Tests](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/tests.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Docs](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/docs.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/wiki)
+[![Code Quality](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/quality.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/actions)
+[![Version](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/version.svg)](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/releases)
+[![Python](https://git.oblachno.oblachno.fyi/oblachno-oss/grm/raw/commit/cc0e4b3fc0c12885c9311773663ec712a37df34b/python.svg)](https://www.python.org/downloads/)
 
 ## Overview
 

docs/tech/architecture.md

@@ -210,12 +210,10 @@ The Python CLI layer (`src/gitea_runner_manager/`) consists of the following mod
 | `executor.py` | Ansible subprocess execution — runs `ansible-playbook` with extra-vars via temp JSON files, streams output to log files |
 | `registry.py` | Local JSON runner registry at `~/.local/share/grm/runners.json` — stores connection metadata |
 | `i18n.py` | Internationalisation translations (en, bg, de, ru, zh, pl) — opt-in via `GRM_LANG` environment variable |
-| `exceptions.py` | Custom exceptions (`GRMError`, `AnsibleError`, `APIError`) |
-| `config.py` | Configuration constants (API URLs, repo owner/name, project IDs) — overridable via environment variables |
+| `exceptions.py` | Custom exceptions (`GRMError`, `AnsibleError`) |
 | `logging_config.py` | Logging configuration — writes all messages to `~/.local/state/grm/logs/grm.log` at DEBUG level |
 | `report.py` | Operation report tracking — prints a step-by-step report with status icons after each command |
 | `ui.py` | User-facing output utilities — colorised console output via `click.style`, with log file always receiving plain text |
-| `api_clients.py` | Gitea and Vikunja API client classes for CI automation scripts (not used by the CLI itself) |
 | `translations.json` | Translation strings for all supported languages |
 
 ## Logging

docs/tech/ci-cd-workflow.md

@@ -74,7 +74,7 @@ Review the full diff (`git diff master...HEAD`) focusing on:
 Post review comments using `devx.ci.pr_review`:
 
 ```bash
-REPO_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
+CI_GITEA_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
   --event REQUEST_CHANGES \
   --body "Review summary" \
   --comments-json comments.json
@@ -89,7 +89,7 @@ Fix each comment one by one, commit, and push. Re-review until satisfied.
 Once all comments are addressed:
 
 ```bash
-REPO_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
+CI_GITEA_TOKEN=<token> python -m devx.ci.pr_review <pr_number> <owner/repo> \
   --event APPROVE \
   --body "All comments addressed. LGTM."
 ```

docs/tech/contributing.md

@@ -137,7 +137,7 @@ Review the full diff (`git diff master...HEAD`) focusing on:
 Post review comments using `devx.ci.review_pr`:
 
 ```bash
-REPO_TOKEN=<token> python -m devx.ci.review_pr <pr_number> <owner/repo> \
+CI_GITEA_TOKEN=<token> python -m devx.ci.review_pr <pr_number> <owner/repo> \
   --event REQUEST_CHANGES \
   --body "Review summary" \
   --comments-json comments.json
@@ -152,10 +152,10 @@ Fix each comment one by one, commit, and push. Re-review until satisfied.
 Once all comments are addressed, post an approval review:
 
 ```bash
-REPO_TOKEN=<token> python -m devx.ci.review_pr <pr_number> <owner/repo> \
+CI_GITEA_TOKEN=<token> python -m devx.ci.review_pr <pr_number> <owner/repo> \
   --event APPROVE --checklist-confirmed \
   --checklist-categories 1,2,3,4,5,6,7,8,9,10,11,12,13 \
-  --body "All 13 REVIEW_CHECKLIST.md categories verified."
+  --body "All 13 checklist categories verified."
 ```
 
 Then add the `ready-to-merge` label. The auto-merge workflow will:
@@ -216,7 +216,7 @@ Not all changes require a new release. The project classifies changes using `dev
 - Lint config files, `.env.example`, `.gitignore`
 
 **User-facing paths** (release needed):
-- `src/gitea_runner_manager/**` (except `__init__.py` and `api_clients.py`)
+- `src/gitea_runner_manager/**` (except `__init__.py`)
 - `ansible/**`
 - `pyproject.toml`
 

docs/tech/decision-log.md

@@ -94,7 +94,7 @@ Key technical decisions for the GRM project, extracted from `CHANGELOG.md` and `
 
 **Decision:** Classify changed files into user-facing and workflow-only categories using `devx.ci.classify_changes`. Only user-facing changes trigger a release; workflow-only changes (CI, docs, tests, lint config) do not.
 
-**Rationale:** Not all changes require a new release. CI workflow updates, documentation improvements, and test additions should not produce a new version tag. The classification is config-driven via `[tool.devx.classify]` in `pyproject.toml`. The strategy is safe-by-default: any file NOT in the explicit workflow-only allowlist is treated as user-facing, preventing new file types from accidentally skipping releases. User-facing paths include `src/gitea_runner_manager/**` (except `__init__.py` and `api_clients.py`) and `ansible/**`. Workflow-only paths include `.gitea/**`, `docs/**`, `tests/**`, `scripts/**`, and various config files.
+**Rationale:** Not all changes require a new release. CI workflow updates, documentation improvements, and test additions should not produce a new version tag. The classification is config-driven via `[tool.devx.classify]` in `pyproject.toml`. The strategy is safe-by-default: any file NOT in the explicit workflow-only allowlist is treated as user-facing, preventing new file types from accidentally skipping releases. User-facing paths include `src/gitea_runner_manager/**` (except `__init__.py`) and `ansible/**`. Workflow-only paths include `.gitea/**`, `docs/**`, `tests/**`, `scripts/**`, and various config files.
 
 **Source:** `AGENTS.md` (Smart CI: User-Facing vs Workflow-Only Changes), `pyproject.toml` (`[tool.devx.classify]`)
 

docs/tech/development-setup.md

@@ -11,11 +11,9 @@
 │   ├── registry.py                # Local JSON runner registry
 │   ├── i18n.py                    # Translations (en, bg, de, ru, zh, pl)
 │   ├── exceptions.py              # Custom exceptions
-│   ├── config.py                  # Configuration constants
 │   ├── logging_config.py          # Logging to ~/.local/state/grm/logs/
 │   ├── report.py                  # Operation report tracking
 │   ├── ui.py                      # Colorised console output
-│   ├── api_clients.py             # Gitea/Vikunja API clients (for CI scripts)
 │   └── translations.json          # Translation strings
 ├── ansible/
 │   ├── roles/gitea-runner/        # Main Ansible role
@@ -108,7 +106,7 @@ cp .env.example .env
 
 #### Admin API token (optional)
 
-Set `REPO_TOKEN` to enable informational API checks during integration test. This is **optional** — the test primarily verifies the runner by checking:
+Set `CI_GITEA_TOKEN` to enable informational API checks during integration test. This is **optional** — the test primarily verifies the runner by checking:
 
 1. **`.runner` registration file** exists and contains valid JSON (proves successful registration)
 2. **Systemd user service** is active (proves daemon is polling for jobs)

docs/user/cli-commands.md

@@ -51,7 +51,7 @@ grm install <host> [options]
 | `--name` | `-n` | hostname | Gitea Runner name |
 | `--token` | `-t` | `GITEA_REGISTRATION_TOKEN` env | Registration token |
 | `--url` | — | `GITEA_URL` env | Gitea URL |
-| `--admin-token` | `-a` | `REPO_TOKEN` env | Gitea admin API token for integration test |
+| `--admin-token` | `-a` | `CI_GITEA_TOKEN` env | Gitea admin API token for integration test |
 | `--integration-retries` | `-r` | `3` (`GITEA_INTEGRATION_RETRIES` env) | Integration test API retries |
 | `--labels` | `-l` | `GITEA_RUNNER_LABELS` env | Runner labels for Gitea Actions. Example: `docker:docker://alpine:latest` |
 | `--ask-become-pass/--no-ask-become-pass` | — | `--ask-become-pass` | Prompt for sudo password (default) or skip it |
@@ -294,7 +294,7 @@ All CLI options can be set via environment variables (loaded from `.env` via pyt
 |----------|---------|-------------|
 | `GITEA_URL` | `install`, `disable`, `remove` | Gitea instance URL |
 | `GITEA_REGISTRATION_TOKEN` | `install`, `disable`, `remove` | Runner registration token |
-| `REPO_TOKEN` | `install` | Admin API token for integration test |
+| `CI_GITEA_TOKEN` | `install` | Admin API token for integration test |
 | `GITEA_INTEGRATION_RETRIES` | `install` | API check retries (default: 3) |
 | `GITEA_RUNNER_USER` | `install`, `update` | Default SSH user |
 | `GITEA_RUNNER_KEY` | `install`, `update` | Default SSH key path |

docs/user/faq.md

@@ -10,9 +10,9 @@ There are three levels of registration tokens, depending on which repositories t
 
 Set the token as `GITEA_REGISTRATION_TOKEN` in your `.env` file or pass it via `--token` on the command line.
 
-### What is the REPO_TOKEN and do I need it?
+### What is the CI_GITEA_TOKEN and do I need it?
 
-`REPO_TOKEN` is a Gitea admin API token used for optional post-install verification. When set, GRM queries the Gitea API after installation to confirm the runner appears in the runner list. This is purely informational — the integration test passes/fails based on the `.runner` file and systemd service, not the API check.
+`CI_GITEA_TOKEN` is a Gitea admin API token used for optional post-install verification. When set, GRM queries the Gitea API after installation to confirm the runner appears in the runner list. This is purely informational — the integration test passes/fails based on the `.runner` file and systemd service, not the API check.
 
 To generate one: Settings → Applications → Generate New Token, with the `admin` scope (or at minimum `read:user`, `read:repository`, `read:admin`).
 

docs/user/getting-started.md

@@ -84,7 +84,7 @@ GITEA_URL=https://git.example.com
 GITEA_REGISTRATION_TOKEN=GRxxxxxxxxxxxxxxxxxx
 
 # Admin API token from Step 2 (optional)
-REPO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
+CI_GITEA_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 ```
 
 ### Environment Variables Reference
@@ -93,7 +93,7 @@ REPO_TOKEN=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
 |----------|----------|---------|-------------|
 | `GITEA_URL` | Yes | — | Gitea instance URL (e.g., `https://git.example.com`) |
 | `GITEA_REGISTRATION_TOKEN` | Yes | — | Runner registration token from Gitea admin panel |
-| `REPO_TOKEN` | No | — | Admin API token for post-install verification |
+| `CI_GITEA_TOKEN` | No | — | Admin API token for post-install verification |
 | `GITEA_INTEGRATION_RETRIES` | No | `3` | API check retries (default: 3) |
 | `GITEA_RUNNER_USER` | No | current login | Default SSH user (overrides `--user`) |
 | `GITEA_RUNNER_KEY` | No | — | Default SSH key path (overrides `--key`) |
@@ -150,7 +150,7 @@ The installer performs an automated integration test that verifies:
 
 You can also check the Gitea UI under **Actions → Runners** to confirm the runner appears as **Online**.
 
-Optional: If `REPO_TOKEN` is set, the installer will also query the Gitea API and report whether the runner appears in the admin or repo runners list. This is purely informational.
+Optional: If `CI_GITEA_TOKEN` is set, the installer will also query the Gitea API and report whether the runner appears in the admin or repo runners list. This is purely informational.
 
 ### Check runner status via CLI
 

docs/user/troubleshooting.md

@@ -98,7 +98,7 @@ The test checks two things:
 
 ### API verification shows error status
 
-If `REPO_TOKEN` is set, the integration test queries the Gitea API. If the API returns `401` or `403`, the token does not have sufficient permissions. This is **informational only** and does not affect pass/fail. The test passes as long as the `.runner` file exists and the systemd service is active.
+If `CI_GITEA_TOKEN` is set, the integration test queries the Gitea API. If the API returns `401` or `403`, the token does not have sufficient permissions. This is **informational only** and does not affect pass/fail. The test passes as long as the `.runner` file exists and the systemd service is active.
 
 ## Logging and Diagnostics
 
@@ -191,7 +191,7 @@ If Docker is not installed, install it via your package manager or [Docker's off
 | Vikunja task not updated after merge | VIKUNJA_TOKEN expired or task ID missing from commit | Regenerate token; verify merge commit has `GRM-N:` prefix |
 | Post-merge can't find Vikunja task | Task not in project 6 or identifier mismatch | Verify task exists in Vikunja project 6 with correct identifier |
 | `make pytest-cov` fails | Coverage below 100% | Add tests for new code paths |
-| `devx.tools.configure_repo` fails | REPO_TOKEN missing or invalid | Set token with repo admin scope and re-run |
+| `devx.tools.configure_repo` fails | CI_GITEA_TOKEN missing or invalid | Set token with repo admin scope and re-run |
 | `configure_repo` sets wrong status checks | Stale `BRANCH_PROTECTION_CONFIG` | Updated to include `(pull_request)` suffix; re-run `configure_repo` |
 | Token visible in `ps aux` during install | Old version passed tokens via command line | Fixed: tokens now passed via temp file with `0600` permissions |
 | `remove-runner.yml` leaves lingering enabled | Old version didn't disable lingering | Fixed: now runs `loginctl disable-linger` and removes subuid/subgid |

pyproject.toml

@@ -14,7 +14,6 @@ classifiers = [
     "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
 ]
 dependencies = [
-    "requests>=2.34.2",
     "python-dotenv>=1.2.2",
     "click>=8.4.1",
     "ansible>=14.0.0",
@@ -27,7 +26,7 @@ grm = "gitea_runner_manager.cli:cli"
 version = {attr = "gitea_runner_manager.__version__"}
 
 [project.optional-dependencies]
-# Minimal deps for CI scripts that only need click/dotenv/requests
+# Minimal deps for CI scripts that only need click/dotenv
 # (detect-changes, discover-runners, pr-review, sync-wiki, badges, etc.)
 ci = [
     "pytest>=9.1.0",
@@ -35,7 +34,7 @@ ci = [
     "build>=1.5.0",
     "twine>=6.2.0",
     # Reusable CI/CD and dev tools (auto-merge, pr-review, pre-push checks, etc.)
-    "devx>=0.15.0",
+    "devx>=0.26.0",
 ]
 # Lint and type-checking tools (quality job)
 lint = [
@@ -55,7 +54,7 @@ molecule = [
 dev = [
     "gitea-runner-manager[ci,lint,molecule]",
     # Reusable CI/CD and dev tools (pre-push hooks, create-task, create-pr)
-    "devx>=0.15.0",
+    "devx>=0.26.0",
     # Non-Python dev dependency: checkmake (Makefile linter)
     # Install via: go install github.com/checkmake/checkmake/cmd/checkmake@latest
 ]
@@ -67,9 +66,9 @@ where = ["src"]
 gitea_runner_manager = ["translations.json"]
 
 [tool.pytest.ini_options]
-testpaths = ["tests"]
-pythonpath = ["src"]
-addopts = "--cov=src/gitea_runner_manager --cov-report=term-missing --cov-fail-under=100"
+testpaths = ["tests", "scripts/tests"]
+pythonpath = ["src", "scripts"]
+addopts = "--cov=src/gitea_runner_manager --cov=scripts/prune_runner_images.py --cov-report=term-missing --cov-fail-under=100"
 markers = [
     "integration: marks tests as integration tests (not counted in coverage)",
 ]
@@ -100,7 +99,19 @@ strict = ["src/gitea_runner_manager"]
 task_prefix = "GRM"
 vikunja_project_id = 6
 repo_owner = "oblachno-oss"
-repo_name = "gitea-runner-manager"
+repo_name = "grm"
+
+# Molecule test weights for LPT scheduling.
+# GRM has a single role (gitea-runner) with 7 scenarios.
+# Weights are estimates — recalibrate from CI logs after next run.
+[tool.devx.molecule.weights]
+"multi-instance" = 8
+"lifecycle" = 6
+"update" = 5
+"default" = 4
+"deregister" = 3
+"remove" = 3
+"template-content" = 2
 
 # lint config, etc.) that applies to any Python project.  We only specify
 # what's different about GRM.
@@ -116,11 +127,8 @@ infrastructure = ["scripts/**"]
 # Infrastructure overrides — files that would default to user-facing
 # but are actually infrastructure:
 # - __init__.py: only contains __version__ (set by release.py, not user code)
-# - api_clients.py: used only by tests and legacy CI scripts (now in devx),
-#   not by the grm CLI tool itself
 infrastructure_overrides = [
     "src/gitea_runner_manager/__init__.py",
-    "src/gitea_runner_manager/api_clients.py",
 ]
 
 # User-facing overrides — safety override for broad infrastructure patterns

scripts/prune_runner_images.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""Prune stale runner images from a rootless Docker daemon.
+
+Usage:
+    python3 prune_runner_images.py [--dry-run]
+
+Removes all images matching the runner-images pattern from the local
+Docker daemon so the runner pulls a fresh :latest on the next job.
+
+Environment variables:
+    DOCKER_HOST     — Docker daemon socket (set by caller)
+    XDG_RUNTIME_DIR — Runtime directory (set by caller)
+"""
+
+from __future__ import annotations
+
+import argparse
+import re
+import subprocess  # nosec B404
+import sys
+from collections.abc import Sequence
+
+#: Pattern for images we want to prune (repository:tag format).
+IMAGE_PATTERN = re.compile(r"runner-images/(ci-base|ci-quality|ci-full)")
+
+
+def list_docker_images() -> list[str]:
+    """List all images in the local Docker daemon as repository:tag strings.
+
+    Returns:
+        List of ``repository:tag`` strings (excluding ``<none>`` entries).
+    """
+    result = subprocess.run(  # nosec B603
+        ["docker", "images", "--format", "{{.Repository}}:{{.Tag}}"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    return [line.strip() for line in result.stdout.splitlines() if line.strip() and "<none>" not in line]
+
+
+def filter_runner_images(images: Sequence[str]) -> list[str]:
+    """Filter image list to only runner-images entries.
+
+    Args:
+        images: List of ``repository:tag`` strings.
+
+    Returns:
+        Subset matching the runner-images pattern.
+    """
+    return [img for img in images if IMAGE_PATTERN.search(img)]
+
+
+def remove_images(images: Sequence[str], dry_run: bool = False) -> list[str]:
+    """Remove the given images from the local Docker daemon.
+
+    Args:
+        images: List of ``repository:tag`` strings to remove.
+        dry_run: If True, print what would be removed but don't execute.
+
+    Returns:
+        List of images that were removed (or would be removed in dry-run).
+    """
+    removed: list[str] = []
+    for img in images:
+        if dry_run:
+            print(f"[dry-run] would remove: {img}")
+            removed.append(img)
+            continue
+        result = subprocess.run(  # nosec B603
+            ["docker", "rmi", "-f", img],
+            capture_output=True,
+            text=True,
+        )
+        if result.returncode == 0:
+            print(f"removed: {img}")
+            removed.append(img)
+        else:
+            print(f"failed to remove {img}: {result.stderr.strip()}", file=sys.stderr)
+    return removed
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Prune stale runner images.")
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Print what would be removed without executing.",
+    )
+    args = parser.parse_args(argv)
+
+    all_images = list_docker_images()
+    runner_images = filter_runner_images(all_images)
+
+    if not runner_images:
+        print("no runner images found to prune")
+        return 0
+
+    removed = remove_images(runner_images, dry_run=args.dry_run)
+    print(f"pruned {len(removed)} image(s)")
+    return 0
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

scripts/tests/test_prune_runner_images.py

@@ -0,0 +1,144 @@
+"""Tests for prune_runner_images.py."""
+
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+from scripts.prune_runner_images import (
+    filter_runner_images,
+    list_docker_images,
+    main,
+    remove_images,
+)
+
+
+class TestListDockerImages:
+    """Tests for list_docker_images()."""
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_returns_images_from_docker(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            stdout="repo1:tag1\nrepo2:tag2\n",
+            returncode=0,
+        )
+        result = list_docker_images()
+        assert result == ["repo1:tag1", "repo2:tag2"]
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_filters_none_entries(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            stdout="repo:tag\n<none>:<none>\nother:v1\n",
+            returncode=0,
+        )
+        result = list_docker_images()
+        assert result == ["repo:tag", "other:v1"]
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_empty_output(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(stdout="", returncode=0)
+        result = list_docker_images()
+        assert result == []
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_strips_whitespace(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(
+            stdout="  repo:tag  \n\n  other:v2  \n",
+            returncode=0,
+        )
+        result = list_docker_images()
+        assert result == ["repo:tag", "other:v2"]
+
+
+class TestFilterRunnerImages:
+    """Tests for filter_runner_images()."""
+
+    def test_matches_runner_images(self) -> None:
+        images = [
+            "git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest",
+            "git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-quality:latest",
+            "git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-full:latest",
+        ]
+        result = filter_runner_images(images)
+        assert len(result) == 3
+
+    def test_excludes_non_runner_images(self) -> None:
+        images = [
+            "docker.io/library/python:3.12",
+            "docker.io/library/nginx:latest",
+            "git.oblachno.oblachno.fyi/oblachno-oss/runner-images/ci-base:latest",
+        ]
+        result = filter_runner_images(images)
+        assert len(result) == 1
+        assert "ci-base" in result[0]
+
+    def test_empty_list(self) -> None:
+        assert filter_runner_images([]) == []
+
+    def test_no_matches(self) -> None:
+        images = ["python:3.12", "nginx:latest"]
+        assert filter_runner_images(images) == []
+
+
+class TestRemoveImages:
+    """Tests for remove_images()."""
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_removes_images(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=0, stderr="")
+        images = ["repo/ci-base:latest", "repo/ci-quality:latest"]
+        removed = remove_images(images)
+        assert removed == images
+        assert mock_run.call_count == 2
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_dry_run_does_not_call_docker(self, mock_run: MagicMock) -> None:
+        images = ["repo/ci-base:latest"]
+        removed = remove_images(images, dry_run=True)
+        assert removed == images
+        mock_run.assert_not_called()
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_failed_removal_not_in_result(self, mock_run: MagicMock) -> None:
+        mock_run.return_value = MagicMock(returncode=1, stderr="image in use")
+        images = ["repo/ci-base:latest"]
+        removed = remove_images(images)
+        assert removed == []
+
+    @patch("scripts.prune_runner_images.subprocess.run")
+    def test_empty_list(self, mock_run: MagicMock) -> None:
+        removed = remove_images([])
+        assert removed == []
+        mock_run.assert_not_called()
+
+
+class TestMain:
+    """Tests for main()."""
+
+    @patch("scripts.prune_runner_images.list_docker_images")
+    @patch("scripts.prune_runner_images.remove_images")
+    def test_no_images(self, mock_remove: MagicMock, mock_list: MagicMock) -> None:
+        mock_list.return_value = []
+        assert main([]) == 0
+        mock_remove.assert_not_called()
+
+    @patch("scripts.prune_runner_images.list_docker_images")
+    @patch("scripts.prune_runner_images.remove_images")
+    def test_with_images(self, mock_remove: MagicMock, mock_list: MagicMock) -> None:
+        mock_list.return_value = [
+            "repo/runner-images/ci-base:latest",
+            "python:3.12",
+        ]
+        mock_remove.return_value = ["repo/runner-images/ci-base:latest"]
+        assert main([]) == 0
+        mock_remove.assert_called_once()
+
+    @patch("scripts.prune_runner_images.list_docker_images")
+    @patch("scripts.prune_runner_images.remove_images")
+    def test_dry_run_flag(self, mock_remove: MagicMock, mock_list: MagicMock) -> None:
+        mock_list.return_value = ["repo/runner-images/ci-base:latest"]
+        mock_remove.return_value = ["repo/runner-images/ci-base:latest"]
+        assert main(["--dry-run"]) == 0
+        mock_remove.assert_called_once_with(
+            ["repo/runner-images/ci-base:latest"],
+            dry_run=True,
+        )

src/gitea_runner_manager/__init__.py

@@ -1,3 +1,3 @@
 """Gitea Runner Manager — lean CLI for managing Gitea Actions runners."""
 
-__version__ = "0.10.0"
+__version__ = "0.11.1"

src/gitea_runner_manager/api_clients.py

@@ -1,353 +0,0 @@
-"""Reusable HTTP API clients for Gitea and Vikunja."""
-
-from __future__ import annotations
-
-import logging
-import time
-from typing import Any
-
-import requests
-
-from .config import DEFAULT_TIMEOUT
-from .exceptions import APIError
-
-logger = logging.getLogger("grm")
-
-# Retry configuration for transient errors (429, 5xx, connection errors)
-MAX_RETRIES = 3
-RETRY_BACKOFF_BASE = 2  # seconds: 2, 4, 8
-RETRY_STATUS_CODES = {429, 500, 502, 503, 504}
-
-
-def _parse_error(e: requests.HTTPError) -> tuple[int, str]:
-    """Extract status code and message from an HTTPError response."""
-    response = getattr(e, "response", None)
-    status = response.status_code if response is not None else 0
-    try:
-        body: dict[str, Any] = response.json() if response is not None else {}
-        message: str = body.get("message", str(e))
-    except Exception:
-        message = str(e)
-    return status, message
-
-
-def _is_retryable(e: Exception) -> bool:
-    """Check if an exception is a transient error worth retrying."""
-    if isinstance(e, requests.ConnectionError):
-        return True
-    if isinstance(e, requests.HTTPError):
-        status, _ = _parse_error(e)
-        return status in RETRY_STATUS_CODES
-    return isinstance(e, requests.Timeout)
-
-
-class GiteaClient:
-    """Low-level Gitea REST API client with connection pooling."""
-
-    def __init__(self, base_url: str, token: str, owner: str, repo: str) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._owner = owner
-        self._repo = repo
-        self._session = requests.Session()
-        self._session.headers.update(
-            {
-                "Authorization": f"token {token}",
-                "Content-Type": "application/json",
-            }
-        )
-
-    def _url(self, path: str) -> str:
-        return f"{self._base_url}/repos/{self._owner}/{self._repo}{path}"
-
-    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
-        url = self._url(path)
-        last_exc: Exception | None = None
-        for attempt in range(MAX_RETRIES):
-            try:
-                response = self._session.request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
-                response.raise_for_status()
-                return response
-            except requests.HTTPError as e:
-                status, message = _parse_error(e)
-                if _is_retryable(e) and attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Transient HTTP %d on %s %s, retrying in %ds (attempt %d/%d)",
-                        status,
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(status, message) from e
-            except (requests.ConnectionError, requests.Timeout) as e:
-                if attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Connection error on %s %s, retrying in %ds (attempt %d/%d)",
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(0, str(e)) from e
-        # Should not reach here, but just in case
-        if last_exc:  # pragma: no cover
-            raise APIError(0, str(last_exc)) from last_exc
-        raise APIError(0, "Max retries exceeded")  # pragma: no cover
-
-    # -- repo settings --
-
-    def update_repo_settings(self, settings: dict[str, Any]) -> dict[str, Any]:
-        """Update repository settings (e.g. auto-delete branch after merge)."""
-        r = self._request("PATCH", "", json=settings)
-        return r.json()
-
-    # -- branch protection --
-
-    def list_branch_protections(self) -> list[dict[str, Any]]:
-        r = self._request("GET", "/branch_protections")
-        return r.json()
-
-    def create_branch_protection(self, config: dict[str, Any]) -> dict[str, Any]:
-        r = self._request("POST", "/branch_protections", json=config)
-        return r.json()
-
-    def update_branch_protection(self, branch: str, config: dict[str, Any]) -> dict[str, Any]:
-        r = self._request("PATCH", f"/branch_protections/{branch}", json=config)
-        return r.json()
-
-    def ensure_branch_protection(self, branch: str, config: dict[str, Any]) -> dict[str, Any]:
-        """Idempotent: create or update branch protection for the given branch."""
-        existing = self.list_branch_protections()
-        for p in existing:
-            if p.get("branch_name") == branch:
-                update_config = {k: v for k, v in config.items() if k != "branch_name"}
-                return self.update_branch_protection(branch, update_config)
-        return self.create_branch_protection(config)
-
-    # -- labels --
-
-    def list_labels(self) -> list[dict[str, Any]]:
-        r = self._request("GET", "/labels")
-        return r.json()
-
-    def create_label(self, name: str, color: str, description: str = "") -> dict[str, Any]:
-        r = self._request(
-            "POST",
-            "/labels",
-            json={"name": name, "color": color, "description": description},
-        )
-        return r.json()
-
-    def ensure_label(self, name: str, color: str, description: str = "") -> dict[str, Any] | None:
-        """Idempotent: create label if it doesn't already exist."""
-        labels = self.list_labels()
-        for label in labels:
-            if label["name"] == name:
-                return None
-        return self.create_label(name, color, description)
-
-    def create_issue(self, title: str, body: str = "", labels: list[int] | None = None) -> dict[str, Any]:
-        """Create a new issue in the repository.
-
-        Args:
-            labels: List of label IDs (integers, not names).
-        """
-        payload: dict[str, Any] = {"title": title, "body": body}
-        if labels:
-            payload["labels"] = labels
-        r = self._request("POST", "/issues", json=payload)
-        return r.json()
-
-    # -- pulls / releases --
-
-    def get_pr_labels(self, pr_number: str | int) -> list[dict[str, Any]]:
-        """Fetch labels currently attached to a pull request."""
-        r = self._request("GET", f"/issues/{pr_number}/labels")
-        return r.json()
-
-    def merge_pr(self, pr_number: str | int, merge_title: str) -> None:
-        payload = {"Do": "squash", "MergeTitleField": merge_title}
-        self._request("POST", f"/pulls/{pr_number}/merge", json=payload)
-
-    def get_commit_status(self, sha: str) -> list[dict[str, Any]]:
-        """Fetch all status check contexts reported for a commit.
-
-        Uses the combined status endpoint (/commits/{sha}/status) which
-        returns one entry per context (the latest), deduplicated server-side.
-        The plural endpoint (/commits/{sha}/statuses) returns every historical
-        entry including stale "pending" ones that never got updated.
-        """
-        r = self._request("GET", f"/commits/{sha}/status")
-        data = r.json()
-        return data.get("statuses", [])
-
-    def get_pr(self, pr_number: str | int) -> dict[str, Any]:
-        """Fetch pull request details including mergeable state."""
-        r = self._request("GET", f"/pulls/{pr_number}")
-        return r.json()
-
-    def get_pr_files(self, pr_number: str | int) -> list[dict[str, Any]]:
-        """Fetch the list of files changed in a pull request."""
-        r = self._request("GET", f"/pulls/{pr_number}/files")
-        return r.json()
-
-    def get_pr_commits(self, pr_number: str | int) -> list[dict[str, Any]]:
-        """Fetch the commits included in a pull request."""
-        r = self._request("GET", f"/pulls/{pr_number}/commits")
-        return r.json()
-
-    def get_pr_reviews(self, pr_number: str | int) -> list[dict[str, Any]]:
-        """Fetch reviews posted on a pull request."""
-        r = self._request("GET", f"/pulls/{pr_number}/reviews")
-        return r.json()
-
-    def create_review(
-        self,
-        pr_number: str | int,
-        event: str = "COMMENT",
-        body: str = "",
-        comments: list[dict[str, Any]] | None = None,
-    ) -> dict[str, Any]:
-        """Post a review on a pull request.
-
-        Args:
-            event: ``APPROVED``, ``REQUEST_CHANGES``, or ``COMMENT``.
-            body: Top-level review body text.
-            comments: Line-level comments with ``path``, ``body``,
-                      ``new_position`` (and optionally ``old_position``).
-        """
-        # Map common event names to Gitea API values
-        event_map = {"APPROVE": "APPROVED", "REQUEST_CHANGES": "REQUEST_CHANGES", "COMMENT": "COMMENT"}
-        gitea_event = event_map.get(event, event)
-        payload: dict[str, Any] = {"event": gitea_event, "body": body}
-        if comments:
-            payload["comments"] = comments
-        r = self._request("POST", f"/pulls/{pr_number}/reviews", json=payload)
-        return r.json()
-
-    def create_release(
-        self,
-        tag: str,
-        name: str = "",
-        body: str = "",
-        draft: bool = False,
-        prerelease: bool = False,
-    ) -> dict[str, Any]:
-        payload = {
-            "tag_name": tag,
-            "name": name or tag,
-            "body": body,
-            "draft": draft,
-            "prerelease": prerelease,
-        }
-        r = self._request("POST", "/releases", json=payload)
-        return r.json()
-
-    def get_release_by_tag(self, tag: str) -> dict[str, Any] | None:
-        """Fetch a release by its tag name. Returns None if not found."""
-        try:
-            r = self._request("GET", f"/releases/tags/{tag}")
-            return r.json()
-        except APIError:
-            return None
-
-    def create_release_idempotent(
-        self,
-        tag: str,
-        name: str = "",
-        body: str = "",
-        draft: bool = False,
-        prerelease: bool = False,
-    ) -> dict[str, Any]:
-        """Create a release, or return the existing one if it already exists.
-
-        This is idempotent — safe to call multiple times for the same tag.
-        """
-        existing = self.get_release_by_tag(tag)
-        if existing:
-            logger.info("Release for tag %s already exists (ID %s), skipping creation.", tag, existing.get("id"))
-            return existing
-        return self.create_release(tag=tag, name=name, body=body, draft=draft, prerelease=prerelease)
-
-
-class VikunjaClient:
-    """Low-level Vikunja REST API client with connection pooling."""
-
-    def __init__(self, base_url: str, token: str) -> None:
-        self._base_url = base_url.rstrip("/")
-        self._session = requests.Session()
-        self._session.headers.update({"Authorization": f"Bearer {token}"})
-
-    def _request(self, method: str, path: str, **kwargs: Any) -> requests.Response:
-        url = f"{self._base_url}{path}"
-        last_exc: Exception | None = None
-        for attempt in range(MAX_RETRIES):
-            try:
-                response = self._session.request(method, url, timeout=DEFAULT_TIMEOUT, **kwargs)
-                response.raise_for_status()
-                return response
-            except requests.HTTPError as e:
-                status, message = _parse_error(e)
-                if _is_retryable(e) and attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Transient HTTP %d on %s %s, retrying in %ds (attempt %d/%d)",
-                        status,
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(status, message) from e
-            except (requests.ConnectionError, requests.Timeout) as e:
-                if attempt < MAX_RETRIES - 1:
-                    wait = RETRY_BACKOFF_BASE ** (attempt + 1)
-                    logger.warning(
-                        "Connection error on %s %s, retrying in %ds (attempt %d/%d)",
-                        method,
-                        path,
-                        wait,
-                        attempt + 1,
-                        MAX_RETRIES,
-                    )
-                    time.sleep(wait)
-                    last_exc = e
-                    continue
-                raise APIError(0, str(e)) from e
-        if last_exc:  # pragma: no cover
-            raise APIError(0, str(last_exc)) from last_exc
-        raise APIError(0, "Max retries exceeded")  # pragma: no cover
-
-    def list_tasks(self, **params: Any) -> list[dict[str, Any]]:
-        r = self._request("GET", "/tasks", params=params)
-        return r.json()
-
-    def get_task(self, task_id: int) -> dict[str, Any]:
-        """Fetch a single task by its numeric ID."""
-        r = self._request("GET", f"/tasks/{task_id}")
-        return r.json()
-
-    def list_project_tasks(self, project_id: int, **params: Any) -> list[dict[str, Any]]:
-        """List tasks in a specific project (more efficient than listing all tasks)."""
-        r = self._request("GET", f"/projects/{project_id}/tasks", params=params)
-        return r.json()
-
-    def post_comment(self, task_id: int, comment: str) -> None:
-        self._request("PUT", f"/tasks/{task_id}/comments", json={"comment": comment})
-
-    def update_task(self, task_id: int, **fields: Any) -> None:
-        self._request("POST", f"/tasks/{task_id}", json=fields)

src/gitea_runner_manager/cli.py

@@ -4,7 +4,9 @@ from __future__ import annotations
 
 import functools
 import os
+import sys
 from collections.abc import Callable
+from pathlib import Path
 from typing import Any
 
 import click
@@ -18,6 +20,34 @@ from .runner_manager import RunnerManager
 load_dotenv(override=True)
 
 
+def _default_user() -> str:
+    """Default SSH user from env or current OS user."""
+    if user := os.getenv("GITEA_RUNNER_USER"):
+        return user
+    try:
+        return os.getlogin()
+    except OSError:
+        return os.getenv("USER", "root")
+
+
+def _get_become_password_file() -> str | None:
+    """Read become-password-file from Click context or env vars."""
+    ctx = click.get_current_context(silent=True)
+    if ctx and ctx.obj:
+        path = ctx.obj.get("become_password_file")
+        if path:
+            return path
+    return os.getenv("GRM_BECOME_PASSWORD_FILE") or os.getenv("ANSIBLE_BECOME_PASSWORD_FILE")
+
+
+def _get_verbose() -> bool:
+    """Read verbose flag from Click context."""
+    ctx = click.get_current_context(silent=True)
+    if ctx and ctx.obj:
+        return ctx.obj.get("verbose", False)
+    return False
+
+
 def _runner_options(func: Callable[..., Any]) -> Callable[..., Any]:
     """Apply common override options for registry-based lifecycle commands."""
     func = click.option(
@@ -49,8 +79,25 @@ def _handle_errors(msg_key: str) -> Callable[[Callable[..., Any]], Callable[...,
 
 @click.group(help=_("Gitea Runner Manager — manage Gitea Actions runners."))
 @click.version_option(version=__version__)
-def cli() -> None:
-    pass
+@click.option(
+    "--become-password-file",
+    envvar="GRM_BECOME_PASSWORD_FILE",
+    type=click.Path(exists=True, dir_okay=False, readable=True),
+    default=None,
+    help=_("Read sudo password from a file instead of prompting (env: GRM_BECOME_PASSWORD_FILE)"),
+)
+@click.option(
+    "--verbose",
+    "-v",
+    is_flag=True,
+    default=False,
+    help=_("Enable verbose Ansible output (-v flag passed to ansible)"),
+)
+@click.pass_context
+def cli(ctx: click.Context, become_password_file: str | None, verbose: bool) -> None:
+    ctx.ensure_object(dict)
+    ctx.obj["become_password_file"] = become_password_file
+    ctx.obj["verbose"] = verbose
 
 
 @cli.command(help=_("Install and configure a Gitea Runner on a remote host."))
@@ -58,8 +105,8 @@ def cli() -> None:
 @click.option(
     "--user",
     "-u",
-    default=lambda: os.getenv("GITEA_RUNNER_USER", os.getlogin()),
-    help=_("SSH user"),
+    default=_default_user,
+    help=_("SSH user (env: GITEA_RUNNER_USER)"),
 )
 @click.option("--key", "-k", default=lambda: os.getenv("GITEA_RUNNER_KEY"), help=_("Path to SSH private key"))
 @click.option("--name", "-n", help=_("Gitea Runner name (default: host)"))
@@ -77,8 +124,8 @@ def cli() -> None:
 @click.option(
     "--admin-token",
     "-a",
-    default=lambda: os.getenv("REPO_TOKEN"),
-    help=_("Gitea admin API token for integration test (env: REPO_TOKEN)"),
+    default=lambda: os.getenv("CI_GITEA_TOKEN"),
+    help=_("Gitea admin API token for integration test (env: CI_GITEA_TOKEN)"),
 )
 @click.option(
     "--integration-retries",
@@ -90,14 +137,19 @@ def cli() -> None:
 @click.option(
     "--labels",
     "-l",
-    default=lambda: os.getenv("GITEA_RUNNER_LABELS", ""),
-    help=_("Runner labels for Gitea Actions (env: GITEA_RUNNER_LABELS). Example: docker:docker://alpine:latest"),
+    default=None,
+    help=_(
+        "Runner labels (env: GITEA_RUNNER_LABELS). "
+        "Pass an empty string for no labels. "
+        "Example: docker:docker://alpine:latest"
+    ),
 )
 @click.option(
     "--ask-become-pass/--no-ask-become-pass",
     default=True,
     help=_("Prompt for sudo password (default)"),
 )
+@_handle_errors("Installation failed: {error}")
 def install(
     host: str,
     user: str,
@@ -107,25 +159,26 @@ def install(
     url: str,
     admin_token: str | None,
     integration_retries: int,
-    labels: str,
+    labels: str | None,
     ask_become_pass: bool,
 ) -> None:
+    if labels is None:
+        labels = os.getenv("GITEA_RUNNER_LABELS")
     manager = RunnerManager()
-    try:
-        manager.install(
-            host=host,
-            user=user,
-            key=key,
-            name=name,
-            token=token,
-            gitea_url=url,
-            admin_token=admin_token,
-            integration_retries=integration_retries,
-            labels=labels or None,
-            ask_become_pass=ask_become_pass,
-        )
-    except GRMError as e:
-        raise click.ClickException(_("Installation failed: {error}", error=e)) from e
+    manager.install(
+        host=host,
+        user=user,
+        key=key,
+        name=name,
+        token=token,
+        gitea_url=url,
+        admin_token=admin_token,
+        integration_retries=integration_retries,
+        labels=labels,
+        ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
+    )
 
 
 @cli.command(help=_("Update the Gitea Runner binary on a remote host."))
@@ -133,8 +186,8 @@ def install(
 @click.option(
     "--user",
     "-u",
-    default=lambda: os.getenv("GITEA_RUNNER_USER", os.getlogin()),
-    help=_("SSH user"),
+    default=_default_user,
+    help=_("SSH user (env: GITEA_RUNNER_USER)"),
 )
 @click.option("--key", "-k", default=lambda: os.getenv("GITEA_RUNNER_KEY"), help=_("Path to SSH private key"))
 @click.option("--version", "-v", help=_("Specific Gitea Runner version"))
@@ -158,6 +211,8 @@ def update(
         key=key,
         version=version,
         ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
@@ -179,6 +234,8 @@ def start(
         user=user,
         key=key,
         ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
@@ -200,6 +257,31 @@ def stop(
         user=user,
         key=key,
         ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
+    )
+
+
+@cli.command(help=_("Restart a registered Gitea Runner (stop, prune images, start)."))
+@click.argument("runner_name")
+@_runner_options
+@_handle_errors("Restart failed: {error}")
+def restart(
+    runner_name: str,
+    host: str | None,
+    user: str | None,
+    key: str | None,
+    ask_become_pass: bool,
+) -> None:
+    manager = RunnerManager()
+    manager.restart(
+        name=runner_name,
+        host=host,
+        user=user,
+        key=key,
+        ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
@@ -221,6 +303,8 @@ def enable(
         user=user,
         key=key,
         ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
@@ -257,6 +341,8 @@ def disable(
         token=token,
         gitea_url=url,
         ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
@@ -278,6 +364,8 @@ def status(
         user=user,
         key=key,
         ask_become_pass=ask_become_pass,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
@@ -322,14 +410,55 @@ def remove(
         gitea_url=url,
         ask_become_pass=ask_become_pass,
         force=force,
+        become_password_file=_get_become_password_file(),
+        verbose=_get_verbose(),
     )
 
 
+def _collect_become_pass(ask_become_pass: bool) -> str | None:
+    """Collect sudo password for ad-hoc status checks.
+
+    Priority:
+    1. ``--become-password-file`` / ``GRM_BECOME_PASSWORD_FILE`` env var
+    2. ``ANSIBLE_BECOME_PASSWORD_FILE`` env var
+    3. Interactive prompt (TTY) or piped stdin (first line)
+    """
+    password_file = _get_become_password_file()
+    if password_file:
+        return Path(password_file).read_text(encoding="utf-8").strip() or None
+    if not ask_become_pass:
+        return None
+    if sys.stdin.isatty():
+        return (
+            click.prompt(
+                _("Sudo password"),
+                hide_input=True,
+                default="",
+                show_default=False,
+            )
+            or None
+        )
+    return sys.stdin.readline().strip() or None
+
+
 @cli.command(name="list", help=_("List all registered runners with live status."))
+@click.option(
+    "--ask-become-pass/--no-ask-become-pass",
+    default=True,
+    help=_("Prompt for sudo password once for all status checks (default)."),
+)
+@click.option(
+    "--no-status",
+    is_flag=True,
+    default=False,
+    help=_("Skip live SSH status checks and show registry entries only"),
+)
 @_handle_errors("List failed: {error}")
-def list_runners() -> None:
+def list_runners(ask_become_pass: bool, no_status: bool) -> None:
+    become_pass = None if no_status else _collect_become_pass(ask_become_pass)
+
     manager = RunnerManager()
-    runners = manager.list_runners()
+    runners = manager.list_runners(become_pass=become_pass, no_status=no_status)
 
     if not runners:
         click.echo(_("No runners registered. Use 'grm install' to add one."))

src/gitea_runner_manager/config.py

@@ -1,43 +0,0 @@
-"""Shared configuration constants for GRM scripts and API clients."""
-
-from __future__ import annotations
-
-import os
-import re
-
-GITEA_API_URL = os.getenv("GRM_GITEA_API_URL", "https://git.oblachno.oblachno.fyi/api/v1")
-VIKUNJA_API_URL = os.getenv("GRM_VIKUNJA_API_URL", "https://work.oblachno.oblachno.fyi/api/v1")
-
-REPO_OWNER = os.getenv("GRM_REPO_OWNER", "oblachno-oss")
-REPO_NAME = os.getenv("GRM_REPO_NAME", "grm")
-
-VIKUNJA_PROJECT_ID = int(os.getenv("GRM_VIKUNJA_PROJECT_ID", "6"))
-
-TASK_ID_RE = re.compile(r"GRM-\d+")
-CONVENTIONAL_RE = re.compile(r"^(feat|fix|chore|docs|style|refactor|perf|test|ci|build|revert)(\(.+\))?: .+")
-
-DEFAULT_TIMEOUT = 30
-DEFAULT_PER_PAGE = 50
-
-BRANCH_PROTECTION_CONFIG: dict[str, object] = {
-    "branch_name": "master",
-    "enable_push": True,
-    "enable_push_whitelist": True,
-    "push_whitelist_usernames": ["emil"],
-    "enable_status_check": True,
-    "status_check_contexts": [
-        "CI / quality (pull_request)",
-        "CI / molecule-tests (1) (pull_request)",
-        "CI / molecule-tests (2) (pull_request)",
-        "CI / molecule-tests (3) (pull_request)",
-    ],
-    "required_approvals": 0,
-    "dismiss_stale_approvals": True,
-    "block_on_outdated_branch": True,
-    "block_on_rejected_reviews": True,
-    "block_on_official_review_requests": True,
-}
-
-REPO_SETTINGS_CONFIG: dict[str, object] = {
-    "default_delete_branch_after_merge": True,
-}

src/gitea_runner_manager/exceptions.py

@@ -11,12 +11,3 @@ class AnsibleError(GRMError):
     """Raised when an Ansible command fails."""
 
     pass
-
-
-class APIError(GRMError):
-    """Raised when a REST API call returns an HTTP error."""
-
-    def __init__(self, status: int, message: str) -> None:
-        self.status = status
-        self.message = message
-        super().__init__(f"HTTP {status}: {message}")

src/gitea_runner_manager/executor.py

@@ -2,11 +2,12 @@
 
 from __future__ import annotations
 
+import contextlib
 import logging
 import os
 import re
 import subprocess  # nosec B404
-import sys
+import tempfile
 from datetime import datetime
 from pathlib import Path
 
@@ -88,8 +89,14 @@ class AnsibleExecutor:
         become: bool = False,
         ask_become_pass: bool = False,
         check: bool = True,
+        become_pass: str | None = None,
     ) -> str:
-        """Run an Ansible ad-hoc command and return stdout."""
+        """Run an Ansible ad-hoc command and return stdout.
+
+        When ``become_pass`` is provided, it is passed via a temporary file
+        (``--become-password-file``) to avoid stdin consumption issues when
+        running multiple ad-hoc commands in sequence (e.g. ``grm list``).
+        """
         cmd = [
             "ansible",
             host,
@@ -104,16 +111,35 @@ class AnsibleExecutor:
             cmd.extend(["--private-key", key])
         if become:
             cmd.append("--become")
-        if become and ask_become_pass and sys.stdin.isatty():
-            cmd.append("--ask-become-pass")
+
+        password_file: str | None = None
+        if become and ask_become_pass:
+            if become_pass:
+                fd, password_file = tempfile.mkstemp(suffix=".txt", prefix="grm-become-")
+                os.fchmod(fd, 0o600)
+                with os.fdopen(fd, "w") as f:
+                    f.write(become_pass)
+                cmd.extend(["--become-password-file", password_file])
+            else:
+                env_password_file = os.getenv("ANSIBLE_BECOME_PASSWORD_FILE")
+                if env_password_file:
+                    cmd.extend(["--become-password-file", env_password_file])
+                else:
+                    cmd.append("--ask-become-pass")
 
         env = os.environ.copy()
-        proc = subprocess.run(  # nosec B603
-            cmd,
-            env=env,
-            capture_output=True,
-            text=True,
-        )
+        try:
+            proc = subprocess.run(  # nosec B603
+                cmd,
+                env=env,
+                capture_output=True,
+                text=True,
+            )
+        finally:
+            if password_file:
+                with contextlib.suppress(FileNotFoundError):
+                    os.unlink(password_file)
+
         if check and proc.returncode != 0:
             stderr = proc.stderr.strip() if proc.stderr else ""
             raise AnsibleError(

src/gitea_runner_manager/i18n.py

@@ -7,12 +7,22 @@ Supported: en, bg, de, ru, zh, pl.
 from __future__ import annotations
 
 import json
+import logging
 import os
 from pathlib import Path
 
-TRANSLATIONS: dict[str, dict[str, str]] = json.loads(
-    (Path(__file__).parent / "translations.json").read_text(encoding="utf-8")
-)
+logger = logging.getLogger("grm")
+
+
+def _load_translations() -> dict[str, dict[str, str]]:
+    try:
+        return json.loads((Path(__file__).parent / "translations.json").read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as e:
+        logger.warning("Failed to load translations.json: %s — falling back to English", e)
+        return {}
+
+
+TRANSLATIONS: dict[str, dict[str, str]] = _load_translations()
 
 
 def _(key: str, **kwargs: object) -> str:

src/gitea_runner_manager/registry.py

@@ -6,6 +6,7 @@ so that subsequent lifecycle commands only need the runner name.
 
 from __future__ import annotations
 
+import fcntl
 import json
 from datetime import UTC, datetime
 from pathlib import Path
@@ -23,20 +24,29 @@ class RunnerRegistry:
         self._data: dict[str, dict[str, Any]] = self._load()
 
     def _load(self) -> dict[str, dict[str, Any]]:
-        if self._path.exists():
-            try:
-                with open(self._path) as f:
+        if not self._path.exists():
+            return {}
+        try:
+            with open(self._path) as f:
+                fcntl.flock(f.fileno(), fcntl.LOCK_SH)
+                try:
                     data: Any = json.load(f)
                     if isinstance(data, dict):
                         return cast(dict[str, dict[str, Any]], data)
-            except (json.JSONDecodeError, OSError):
-                pass
+                finally:
+                    fcntl.flock(f.fileno(), fcntl.LOCK_UN)
+        except (json.JSONDecodeError, OSError):
+            pass
         return {}
 
     def _save(self) -> None:
         self._path.parent.mkdir(parents=True, exist_ok=True)
         with open(self._path, "w") as f:
-            json.dump(self._data, f, indent=2)
+            fcntl.flock(f.fileno(), fcntl.LOCK_EX)
+            try:
+                json.dump(self._data, f, indent=2)
+            finally:
+                fcntl.flock(f.fileno(), fcntl.LOCK_UN)
 
     def add(
         self,

src/gitea_runner_manager/report.py

@@ -49,7 +49,6 @@ def track_steps() -> Generator[StepTracker, None, None]:
         for step in reversed(tracker.steps):
             if step.status == "in_progress":
                 step.status = "failed"
-                break
         raise
     finally:
         _print_report(tracker.steps)

src/gitea_runner_manager/runner_manager.py

@@ -2,12 +2,11 @@
 
 from __future__ import annotations
 
-import contextlib
 import json
 import os
 import tempfile
 from collections.abc import Generator
-from contextlib import contextmanager
+from contextlib import contextmanager, suppress
 from pathlib import Path
 
 from .exceptions import AnsibleError
@@ -42,12 +41,12 @@ class RunnerManager:
             return
         fd, path = tempfile.mkstemp(suffix=".json", prefix="grm-vars-")
         try:
+            os.fchmod(fd, 0o600)
             with os.fdopen(fd, "w") as f:
                 json.dump(extra_vars, f)
-            os.chmod(path, 0o600)
             yield path
         finally:
-            with contextlib.suppress(FileNotFoundError):
+            with suppress(FileNotFoundError):
                 os.unlink(path)
 
     def _run_playbook(
@@ -59,10 +58,21 @@ class RunnerManager:
         key: str | None = None,
         ask_become_pass: bool = False,
         description: str = "",
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Build command with temp-file extra-vars and execute via executor."""
         with self._extra_vars_file(extra_vars) as vars_file:
-            cmd = self._build_cmd(playbook_name, host, user, vars_file, key, ask_become_pass)
+            cmd = self._build_cmd(
+                playbook_name,
+                host,
+                user,
+                vars_file,
+                key,
+                ask_become_pass,
+                become_password_file,
+                verbose,
+            )
             self._executor.run(cmd, description=description)
 
     def install(
@@ -77,6 +87,8 @@ class RunnerManager:
         integration_retries: int = 3,
         ask_become_pass: bool = False,
         labels: str | None = None,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Install a runner on a remote host using Ansible."""
         if not name:
@@ -94,7 +106,7 @@ class RunnerManager:
         }
         if admin_token:
             extra_vars["gitea_admin_token"] = admin_token
-        if labels:
+        if labels is not None:
             extra_vars["runner_labels"] = labels
 
         with track_steps() as tracker:
@@ -107,6 +119,8 @@ class RunnerManager:
                 key,
                 ask_become_pass,
                 description=_("Installing Gitea Runner on {host}", host=host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -128,6 +142,8 @@ class RunnerManager:
         key: str | None = None,
         version: str | None = None,
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Update the gitea_runner binary on a remote host."""
         extra_vars: dict[str, str | int] | None = None
@@ -144,6 +160,8 @@ class RunnerManager:
                 key,
                 ask_become_pass,
                 description=_("Updating Gitea Runner on {host}", host=host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -187,6 +205,8 @@ class RunnerManager:
         user: str | None = None,
         key: str | None = None,
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Start a runner instance on a remote host."""
         actual_host, actual_user, actual_key, _gitea_url = self._resolve_runner(name, host, user, key)
@@ -200,6 +220,8 @@ class RunnerManager:
                 actual_key,
                 ask_become_pass,
                 description=_("Starting Gitea Runner {name} on {host}", name=name, host=actual_host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -210,6 +232,8 @@ class RunnerManager:
         user: str | None = None,
         key: str | None = None,
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Stop a runner instance on a remote host."""
         actual_host, actual_user, actual_key, _gitea_url = self._resolve_runner(name, host, user, key)
@@ -223,6 +247,35 @@ class RunnerManager:
                 actual_key,
                 ask_become_pass,
                 description=_("Stopping Gitea Runner {name} on {host}", name=name, host=actual_host),
+                become_password_file=become_password_file,
+                verbose=verbose,
+            )
+            tracker.done()
+
+    def restart(
+        self,
+        name: str,
+        host: str | None = None,
+        user: str | None = None,
+        key: str | None = None,
+        ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
+    ) -> None:
+        """Restart a runner instance on a remote host (stop, prune images, start)."""
+        actual_host, actual_user, actual_key, _gitea_url = self._resolve_runner(name, host, user, key)
+        with track_steps() as tracker:
+            tracker.begin(_("Restarting Gitea Runner {name} on {host}", name=name, host=actual_host))
+            self._run_playbook(
+                "restart-runner.yml",
+                actual_host,
+                actual_user,
+                {"runner_name": name},
+                actual_key,
+                ask_become_pass,
+                description=_("Restarting Gitea Runner {name} on {host}", name=name, host=actual_host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -233,6 +286,8 @@ class RunnerManager:
         user: str | None = None,
         key: str | None = None,
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Enable a runner instance to start on boot."""
         actual_host, actual_user, actual_key, _gitea_url = self._resolve_runner(name, host, user, key)
@@ -246,6 +301,8 @@ class RunnerManager:
                 actual_key,
                 ask_become_pass,
                 description=_("Enabling Gitea Runner {name} on {host}", name=name, host=actual_host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -258,6 +315,8 @@ class RunnerManager:
         token: str | None = None,
         gitea_url: str = "",
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Disable and deregister a runner instance."""
         actual_host, actual_user, actual_key, registry_gitea_url = self._resolve_runner(name, host, user, key)
@@ -276,6 +335,8 @@ class RunnerManager:
                 actual_key,
                 ask_become_pass,
                 description=_("Disabling Gitea Runner {name} on {host}", name=name, host=actual_host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -286,6 +347,8 @@ class RunnerManager:
         user: str | None = None,
         key: str | None = None,
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Check the status of a runner instance."""
         actual_host, actual_user, actual_key, _gitea_url = self._resolve_runner(name, host, user, key)
@@ -299,6 +362,8 @@ class RunnerManager:
                 actual_key,
                 ask_become_pass,
                 description=_("Checking status of Gitea Runner {name} on {host}", name=name, host=actual_host),
+                become_password_file=become_password_file,
+                verbose=verbose,
             )
             tracker.done()
 
@@ -312,6 +377,8 @@ class RunnerManager:
         gitea_url: str = "",
         ask_become_pass: bool = False,
         force: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> None:
         """Remove a runner instance completely.
 
@@ -338,6 +405,8 @@ class RunnerManager:
                     actual_key,
                     ask_become_pass,
                     description=_("Removing Gitea Runner {name} from {host}", name=name, host=actual_host),
+                    become_password_file=become_password_file,
+                    verbose=verbose,
                 )
             tracker.done()
 
@@ -345,14 +414,38 @@ class RunnerManager:
             self._registry.remove(name)
             tracker.done()
 
-    def list_runners(self) -> list[dict[str, str]]:
-        """Return a list of registered runners with live service status."""
+    def list_runners(
+        self,
+        become_pass: str | None = None,
+        no_status: bool = False,
+    ) -> list[dict[str, str]]:
+        """Return a list of registered runners with live service status.
+
+        Args:
+            become_pass: Sudo password for ad-hoc status checks. When provided,
+                it is passed via ``--become-password-file`` to avoid stdin
+                consumption issues when checking multiple runners in sequence.
+            no_status: Skip live SSH status checks and return ``"n/a"`` for status.
+        """
         runners = self._registry.list()
         result: list[dict[str, str]] = []
         for name, info in runners.items():
             host = info["host"]
             user = info["user"]
             key = info.get("key")
+
+            if no_status:
+                result.append(
+                    {
+                        "name": name,
+                        "host": host,
+                        "user": user,
+                        "labels": info.get("labels", ""),
+                        "status": _("n/a"),
+                    }
+                )
+                continue
+
             say(
                 _(
                     "Checking status of Gitea Runner {name} on {host} as {user} (sudo required)",
@@ -369,10 +462,13 @@ class RunnerManager:
                     user,
                     key,
                     "shell",
-                    f"sudo -u grm-{name} systemctl --user is-active gitea-runner 2>/dev/null",
+                    f"sudo -u grm-{name} "
+                    f"XDG_RUNTIME_DIR=/run/user/$(id -u grm-{name}) "
+                    f"systemctl --user is-active gitea-runner 2>/dev/null",
                     become=True,
-                    ask_become_pass=True,
+                    ask_become_pass=become_pass is not None,
                     check=False,
+                    become_pass=become_pass,
                 )
                 service_status = self._parse_status(stdout)
             except AnsibleError:
@@ -405,6 +501,8 @@ class RunnerManager:
         extra_vars_file: str | None = None,
         key: str | None = None,
         ask_become_pass: bool = False,
+        become_password_file: str | None = None,
+        verbose: bool = False,
     ) -> list[str]:
         """Build the ansible-playbook command.
 
@@ -427,6 +525,10 @@ class RunnerManager:
             cmd.extend(["--extra-vars", f"@{extra_vars_file}"])
         if key:
             cmd.extend(["--private-key", key])
-        if ask_become_pass:
+        if become_password_file:
+            cmd.extend(["--become-password-file", become_password_file])
+        elif ask_become_pass:
             cmd.append("--ask-become-pass")
+        if verbose:
+            cmd.append("-v")
         return cmd

src/gitea_runner_manager/translations.json

@@ -103,6 +103,14 @@
     "ru": "Включение не удалось: {error}",
     "zh": "启用失败: {error}"
   },
+  "Enable verbose Ansible output (-v flag passed to ansible)": {
+    "bg": "Подробен изход от Ansible (-v флаг към ansible)",
+    "de": "Ausführliche Ansible-Ausgabe (-v Flag an ansible)",
+    "en": "Enable verbose Ansible output (-v flag passed to ansible)",
+    "pl": "Szczegółowe wyjście Ansible (flaga -v przekazana do ansible)",
+    "ru": "Подробный вывод Ansible (флаг -v передаётся в ansible)",
+    "zh": "启用 Ansible 详细输出（-v 标志传递给 ansible）"
+  },
   "Enabling Gitea Runner {name} on {host}": {
     "bg": "Активиране на Gitea Runner {name} на {host}",
     "de": "Aktiviere Gitea Runner {name} auf {host}",
@@ -159,13 +167,13 @@
     "ru": "URL Gitea (env: GITEA_URL)",
     "zh": "Gitea URL（环境变量: GITEA_URL）"
   },
-  "Gitea admin API token for integration test (env: REPO_TOKEN)": {
-    "bg": "Gitea admin API токен за интеграционен тест (env: REPO_TOKEN)",
-    "de": "Gitea-Admin-API-Token für Integrationstest (env: REPO_TOKEN)",
-    "en": "Gitea admin API token for integration test (env: REPO_TOKEN)",
-    "pl": "Token API administratora Gitea do testów integracyjnych (env: REPO_TOKEN)",
-    "ru": "Токен админ API Gitea для интеграционного теста (env: REPO_TOKEN)",
-    "zh": "Gitea 管理员 API 令牌，用于集成测试（环境变量: REPO_TOKEN）"
+  "Gitea admin API token for integration test (env: CI_GITEA_TOKEN)": {
+    "bg": "Gitea admin API токен за интеграционен тест (env: CI_GITEA_TOKEN)",
+    "de": "Gitea-Admin-API-Token für Integrationstest (env: CI_GITEA_TOKEN)",
+    "en": "Gitea admin API token for integration test (env: CI_GITEA_TOKEN)",
+    "pl": "Token API administratora Gitea do testów integracyjnych (env: CI_GITEA_TOKEN)",
+    "ru": "Токен админ API Gitea для интеграционного теста (env: CI_GITEA_TOKEN)",
+    "zh": "Gitea 管理员 API 令牌，用于集成测试（环境变量: CI_GITEA_TOKEN）"
   },
   "HOST": {
     "bg": "ХОСТ",
@@ -239,6 +247,14 @@
     "ru": "ИМЯ",
     "zh": "名称"
   },
+  "n/a": {
+    "bg": "н/д",
+    "de": "n. v.",
+    "en": "n/a",
+    "pl": "n/d",
+    "ru": "н/д",
+    "zh": "不适用"
+  },
   "No runners registered. Use 'grm install' to add one.": {
     "bg": "Няма регистрирани runners. Използвайте 'grm install', за да добавите.",
     "de": "Keine Runner registriert. Verwenden Sie 'grm install', um einen hinzuzufügen.",
@@ -295,6 +311,14 @@
     "ru": "Запросить пароль sudo (по умолчанию)",
     "zh": "提示输入 sudo 密码（默认）"
   },
+  "Prompt for sudo password once for all status checks (default).": {
+    "bg": "Подканване за sudo парола веднъж за всички проверки на състоянието (по подразбиране).",
+    "de": "Einmal nach sudo-Passwort für alle Statusprüfungen fragen (Standard).",
+    "en": "Prompt for sudo password once for all status checks (default).",
+    "pl": "Zapytaj o hasło sudo raz dla wszystkich sprawdzeń statusu (domyślnie).",
+    "ru": "Запросить пароль sudo один раз для всех проверок статуса (по умолчанию).",
+    "zh": "为所有状态检查提示一次 sudo 密码（默认）。"
+  },
   "Registration token (env: GITEA_REGISTRATION_TOKEN)": {
     "bg": "Регистрационен токен (env: GITEA_REGISTRATION_TOKEN)",
     "de": "Registrierungstoken (env: GITEA_REGISTRATION_TOKEN)",
@@ -335,6 +359,38 @@
     "ru": "Удаление Gitea Runner {name} с {host}",
     "zh": "正在从 {host} 移除 Gitea Runner {name}"
   },
+  "Read sudo password from a file instead of prompting (env: GRM_BECOME_PASSWORD_FILE)": {
+    "bg": "Четене на sudo парола от файл вместо интерактивно (env: GRM_BECOME_PASSWORD_FILE)",
+    "de": "Sudo-Passwort aus Datei lesen statt abfragen (env: GRM_BECOME_PASSWORD_FILE)",
+    "en": "Read sudo password from a file instead of prompting (env: GRM_BECOME_PASSWORD_FILE)",
+    "pl": "Odczytaj hasło sudo z pliku zamiast pytać (env: GRM_BECOME_PASSWORD_FILE)",
+    "ru": "Читать sudo-пароль из файла вместо ввода (env: GRM_BECOME_PASSWORD_FILE)",
+    "zh": "从文件读取 sudo 密码而非提示输入（环境变量: GRM_BECOME_PASSWORD_FILE）"
+  },
+  "Restart a registered Gitea Runner (stop, prune images, start).": {
+    "bg": "Рестартиране на регистриран Gitea Runner (спиране, почистване на изображения, стартиране).",
+    "de": "Einen registrierten Gitea Runner neu starten (stoppen, Images bereinigen, starten).",
+    "en": "Restart a registered Gitea Runner (stop, prune images, start).",
+    "pl": "Uruchom ponownie zarejestrowanego Gitea Runner (zatrzymaj, wyczyść obrazy, uruchom).",
+    "ru": "Перезапустить зарегистрированный Gitea Runner (остановить, очистить образы, запустить).",
+    "zh": "重启已注册的 Gitea Runner（停止、清理镜像、启动）。"
+  },
+  "Restart failed: {error}": {
+    "bg": "Рестартирането неуспешно: {error}",
+    "de": "Neustart fehlgeschlagen: {error}",
+    "en": "Restart failed: {error}",
+    "pl": "Ponowne uruchomienie nie powiodło się: {error}",
+    "ru": "Перезапуск не удался: {error}",
+    "zh": "重启失败: {error}"
+  },
+  "Restarting Gitea Runner {name} on {host}": {
+    "bg": "Рестартиране на Gitea Runner {name} на {host}",
+    "de": "Starte Gitea Runner {name} auf {host} neu",
+    "en": "Restarting Gitea Runner {name} on {host}",
+    "pl": "Ponowne uruchamianie Gitea Runner {name} na {host}",
+    "ru": "Перезапуск Gitea Runner {name} на {host}",
+    "zh": "正在 {host} 上重启 Gitea Runner {name}"
+  },
   "Runner '{name}' not found in registry.": {
     "bg": "Runner '{name}' не е намерен в регистъра.",
     "de": "Runner '{name}' nicht in der Registrierung gefunden.",
@@ -351,13 +407,13 @@
     "ru": "Runner '{name}' не найден в реестре. Сначала используйте 'grm install' или укажите --host и --user.",
     "zh": "注册表中未找到 Runner '{name}'。请先使用 'grm install' 或提供 --host 和 --user。"
   },
-  "Runner labels for Gitea Actions (env: GITEA_RUNNER_LABELS). Example: docker:docker://alpine:latest": {
-    "bg": "Етикети на runner за Gitea Actions (env: GITEA_RUNNER_LABELS). Пример: docker:docker://alpine:latest",
-    "de": "Runner-Labels für Gitea Actions (env: GITEA_RUNNER_LABELS). Beispiel: docker:docker://alpine:latest",
-    "en": "Runner labels for Gitea Actions (env: GITEA_RUNNER_LABELS). Example: docker:docker://alpine:latest",
-    "pl": "Etykiety runnera dla Gitea Actions (env: GITEA_RUNNER_LABELS). Przykład: docker:docker://alpine:latest",
-    "ru": "Метки runner для Gitea Actions (env: GITEA_RUNNER_LABELS). Пример: docker:docker://alpine:latest",
-    "zh": "Gitea Actions 的 runner 标签（环境变量: GITEA_RUNNER_LABELS）。示例: docker:docker://alpine:latest"
+  "Runner labels (env: GITEA_RUNNER_LABELS). Pass an empty string for no labels. Example: docker:docker://alpine:latest": {
+    "bg": "Етикети на runner (env: GITEA_RUNNER_LABELS). Подайте празен низ за без етикети. Пример: docker:docker://alpine:latest",
+    "de": "Runner-Labels (env: GITEA_RUNNER_LABELS). Leerstring für keine Labels. Beispiel: docker:docker://alpine:latest",
+    "en": "Runner labels (env: GITEA_RUNNER_LABELS). Pass an empty string for no labels. Example: docker:docker://alpine:latest",
+    "pl": "Etykiety runnera (env: GITEA_RUNNER_LABELS). Pusty ciąg = brak etykiet. Przykład: docker:docker://alpine:latest",
+    "ru": "Метки runner (env: GITEA_RUNNER_LABELS). Пустая строка = без меток. Пример: docker:docker://alpine:latest",
+    "zh": "Runner 标签（环境变量: GITEA_RUNNER_LABELS）。空字符串表示无标签。示例: docker:docker://alpine:latest"
   },
   "Running Ansible playbook": {
     "bg": "Изпълнение на Ansible playbook",
@@ -367,13 +423,13 @@
     "ru": "Выполнение Ansible playbook",
     "zh": "正在运行 Ansible playbook"
   },
-  "SSH user": {
-    "bg": "SSH потребител",
-    "de": "SSH-Benutzer",
-    "en": "SSH user",
-    "pl": "Użytkownik SSH",
-    "ru": "SSH пользователь",
-    "zh": "SSH 用户"
+  "SSH user (env: GITEA_RUNNER_USER)": {
+    "bg": "SSH потребител (env: GITEA_RUNNER_USER)",
+    "de": "SSH-Benutzer (env: GITEA_RUNNER_USER)",
+    "en": "SSH user (env: GITEA_RUNNER_USER)",
+    "pl": "Użytkownik SSH (env: GITEA_RUNNER_USER)",
+    "ru": "SSH пользователь (env: GITEA_RUNNER_USER)",
+    "zh": "SSH 用户（环境变量: GITEA_RUNNER_USER）"
   },
   "STATUS": {
     "bg": "СТАТУС",
@@ -399,6 +455,14 @@
     "ru": "Пропустить удаленную очистку и удалить только локальную запись реестра",
     "zh": "跳过远程清理，仅删除本地注册表条目"
   },
+  "Skip live SSH status checks and show registry entries only": {
+    "bg": "Пропуснете проверките на SSH състоянието и покажете само записите от регистъра",
+    "de": "Live-SSH-Statusprüfungen überspringen und nur Registrierungseinträge anzeigen",
+    "en": "Skip live SSH status checks and show registry entries only",
+    "pl": "Pomiń sprawdzanie statusu SSH i pokaż tylko wpisy z rejestru",
+    "ru": "Пропустить проверки статуса SSH и показать только записи реестра",
+    "zh": "跳过 SSH 状态检查，仅显示注册表条目"
+  },
   "Specific Gitea Runner version": {
     "bg": "Конкретна версия на Gitea Runner",
     "de": "Spezifische Gitea Runner-Version",
@@ -463,6 +527,14 @@
     "ru": "Остановка Gitea Runner {name} на {host}",
     "zh": "正在 {host} 上停止 Gitea Runner {name}"
   },
+  "Sudo password": {
+    "bg": "Sudo парола",
+    "de": "Sudo-Passwort",
+    "en": "Sudo password",
+    "pl": "Hasło sudo",
+    "ru": "Пароль sudo",
+    "zh": "Sudo 密码"
+  },
   "USER": {
     "bg": "ПОТРЕБИТЕЛ",
     "de": "BENUTZER",

tests/integration/test_lifecycle.py

@@ -30,21 +30,39 @@ class TestLifecycleCLI:
         result = runner.invoke(cli, ["start", "r1", "--host", "host1", "--user", "ubuntu", "--no-ask-become-pass"])
         assert result.exit_code == 0
         mock_manager.start.assert_called_once_with(
-            host="host1", user="ubuntu", name="r1", key=None, ask_become_pass=False
+            host="host1",
+            user="ubuntu",
+            name="r1",
+            key=None,
+            ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )
 
         # Status
         result = runner.invoke(cli, ["status", "r1", "--host", "host1", "--user", "ubuntu", "--no-ask-become-pass"])
         assert result.exit_code == 0
         mock_manager.status.assert_called_once_with(
-            host="host1", user="ubuntu", name="r1", key=None, ask_become_pass=False
+            host="host1",
+            user="ubuntu",
+            name="r1",
+            key=None,
+            ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )
 
         # Stop
         result = runner.invoke(cli, ["stop", "r1", "--host", "host1", "--user", "ubuntu", "--no-ask-become-pass"])
         assert result.exit_code == 0
         mock_manager.stop.assert_called_once_with(
-            host="host1", user="ubuntu", name="r1", key=None, ask_become_pass=False
+            host="host1",
+            user="ubuntu",
+            name="r1",
+            key=None,
+            ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )
 
         # Disable
@@ -61,6 +79,8 @@ class TestLifecycleCLI:
             token="tok",
             gitea_url="https://git.example.com",
             ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )
 
         # Remove
@@ -78,4 +98,6 @@ class TestLifecycleCLI:
             gitea_url="https://git.example.com",
             ask_become_pass=False,
             force=False,
+            become_password_file=None,
+            verbose=False,
         )

tests/integration/test_multi_instance.py

@@ -47,11 +47,23 @@ class TestMultiInstanceCLI:
         )
         assert result.exit_code == 0
         mock_manager.start.assert_called_once_with(
-            host="host1", user="ubuntu", name="runner-a", key=None, ask_become_pass=False
+            host="host1",
+            user="ubuntu",
+            name="runner-a",
+            key=None,
+            ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )
 
         result = runner.invoke(cli, ["stop", "runner-b", "--host", "host1", "--user", "ubuntu", "--no-ask-become-pass"])
         assert result.exit_code == 0
         mock_manager.stop.assert_called_once_with(
-            host="host1", user="ubuntu", name="runner-b", key=None, ask_become_pass=False
+            host="host1",
+            user="ubuntu",
+            name="runner-b",
+            key=None,
+            ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )

tests/unit/test_api_clients.py

@@ -1,642 +0,0 @@
-"""Unit tests for api_clients module."""
-
-import http
-from unittest.mock import MagicMock, patch
-
-import pytest
-import requests
-
-from gitea_runner_manager.api_clients import GiteaClient, VikunjaClient, _is_retryable, _parse_error
-from gitea_runner_manager.config import (
-    BRANCH_PROTECTION_CONFIG,
-    DEFAULT_PER_PAGE,
-    DEFAULT_TIMEOUT,
-    VIKUNJA_PROJECT_ID,
-)
-from gitea_runner_manager.exceptions import APIError
-
-
-def _mock_response(json_data: object | None = None, raise_on_status: bool = False) -> MagicMock:
-    mock = MagicMock()
-    if json_data is not None:
-        mock.json.return_value = json_data
-    if raise_on_status:
-        mock.raise_for_status.side_effect = requests.HTTPError(str(http.HTTPStatus.INTERNAL_SERVER_ERROR))
-    return mock
-
-
-def _mock_http_error(status_code: int, message: str = "") -> requests.HTTPError:
-    """Create an HTTPError with a proper response attached (for _parse_error)."""
-    resp = MagicMock()
-    resp.status_code = status_code
-    resp.json.return_value = {"message": message or str(status_code)}
-    err = requests.HTTPError(f"{status_code} {message}", response=resp)
-    return err
-
-
-class TestParseError:
-    def test_json_parse_fallback(self) -> None:
-        mock_response = MagicMock()
-        mock_response.status_code = http.HTTPStatus.BAD_GATEWAY
-        mock_response.json = MagicMock(side_effect=ValueError("not json"))
-        err = requests.HTTPError(str(http.HTTPStatus.BAD_GATEWAY), response=mock_response)
-        status, message = _parse_error(err)
-        assert status == http.HTTPStatus.BAD_GATEWAY
-        assert str(http.HTTPStatus.BAD_GATEWAY) in message
-
-    def test_no_response(self) -> None:
-        err = requests.HTTPError("connection failed")
-        err.response = None  # type: ignore[assignment]
-        status, message = _parse_error(err)
-        assert status == 0
-        assert "connection failed" in message
-
-
-class TestGiteaClient:
-    def test_init_sets_headers(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        assert client._base_url == "https://git.example.com"
-        assert client._session.headers["Authorization"] == "token tok"
-        assert client._session.headers["Content-Type"] == "application/json"
-
-    def test_url_constructs_path(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        assert client._url("/labels") == ("https://git.example.com/repos/owner/repo/labels")
-
-    def test_url_strips_trailing_slash(self) -> None:
-        client = GiteaClient("https://git.example.com/", "tok", "owner", "repo")
-        assert client._url("/labels") == ("https://git.example.com/repos/owner/repo/labels")
-
-    def test_list_labels(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response([{"name": "bug", "color": "ff0000"}]))
-        result = client.list_labels()
-        assert len(result) == 1
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/labels",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_list_labels_raises_api_error(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response(raise_on_status=True))
-        with pytest.raises(APIError):
-            client.list_labels()
-
-    def test_http_error_json_parse_fallback(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        mock_response = MagicMock()
-        mock_response.status_code = http.HTTPStatus.BAD_GATEWAY
-        # Make json() itself raise so the except block in _parse_error is hit
-        mock_response.json = MagicMock(side_effect=ValueError("not json"))
-        mock_response.raise_for_status.side_effect = requests.HTTPError(str(http.HTTPStatus.BAD_GATEWAY))
-        client._session.request = MagicMock(return_value=mock_response)
-        with pytest.raises(APIError) as exc_info:
-            client.list_labels()
-        assert str(http.HTTPStatus.BAD_GATEWAY) in str(exc_info.value)
-
-    def test_create_label(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"name": "ready-to-merge", "color": "2ecc71"}))
-        result = client.create_label("ready-to-merge", "2ecc71", "Auto-merge label")
-        assert result["name"] == "ready-to-merge"
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/labels",
-            timeout=DEFAULT_TIMEOUT,
-            json={"name": "ready-to-merge", "color": "2ecc71", "description": "Auto-merge label"},
-        )
-
-    def test_ensure_label_creates_when_not_exists(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client.list_labels = MagicMock(return_value=[])
-        client.create_label = MagicMock(return_value={"name": "ready-to-merge", "color": "2ecc71"})
-
-        result = client.ensure_label("ready-to-merge", "2ecc71", "desc")
-        assert result is not None
-        assert result["name"] == "ready-to-merge"
-        client.create_label.assert_called_once_with("ready-to-merge", "2ecc71", "desc")
-
-    def test_ensure_label_returns_none_when_exists(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client.list_labels = MagicMock(return_value=[{"name": "ready-to-merge", "color": "2ecc71"}])
-        client.create_label = MagicMock()
-
-        result = client.ensure_label("ready-to-merge", "2ecc71", "desc")
-        assert result is None
-        client.create_label.assert_not_called()
-
-    def test_list_branch_protections(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(
-            return_value=_mock_response(
-                [
-                    {"id": 1, "branch_name": "master"},
-                    {"id": 2, "branch_name": "develop"},
-                ]
-            )
-        )
-        result = client.list_branch_protections()
-        assert len(result) == 2
-        assert result[0]["branch_name"] == "master"
-
-    def test_create_branch_protection(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 3, "branch_name": "master"}))
-        result = client.create_branch_protection(BRANCH_PROTECTION_CONFIG)
-        assert result["id"] == 3
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/branch_protections",
-            timeout=DEFAULT_TIMEOUT,
-            json=BRANCH_PROTECTION_CONFIG,
-        )
-
-    def test_update_branch_protection(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        resp = {"branch_name": "master", "required_approvals": 2}
-        client._session.request = MagicMock(return_value=_mock_response(resp))
-        update = {"required_approvals": 2}
-        result = client.update_branch_protection("master", update)
-        assert result["required_approvals"] == 2
-        client._session.request.assert_called_once_with(
-            "PATCH",
-            "https://git.example.com/repos/owner/repo/branch_protections/master",
-            timeout=DEFAULT_TIMEOUT,
-            json=update,
-        )
-
-    def test_ensure_branch_protection_creates_when_none_exist(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client.list_branch_protections = MagicMock(return_value=[])
-        client.create_branch_protection = MagicMock(return_value={"id": 1, "branch_name": "master"})
-
-        result = client.ensure_branch_protection("master", BRANCH_PROTECTION_CONFIG)
-        assert result["id"] == 1
-        client.create_branch_protection.assert_called_once_with(BRANCH_PROTECTION_CONFIG)
-
-    def test_ensure_branch_protection_updates_when_exists(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client.list_branch_protections = MagicMock(return_value=[{"branch_name": "master", "required_approvals": 0}])
-        client.update_branch_protection = MagicMock(return_value={"branch_name": "master", "required_approvals": 1})
-
-        result = client.ensure_branch_protection("master", BRANCH_PROTECTION_CONFIG)
-        assert result["required_approvals"] == 1
-        expected_update = {k: v for k, v in BRANCH_PROTECTION_CONFIG.items() if k != "branch_name"}
-        client.update_branch_protection.assert_called_once_with("master", expected_update)
-
-    def test_merge_pr(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response())
-
-        client.merge_pr(1, "fix: bug")
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/pulls/1/merge",
-            timeout=DEFAULT_TIMEOUT,
-            json={"Do": "squash", "MergeTitleField": "fix: bug"},
-        )
-
-    def test_get_pr_labels(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response([{"name": "ready-to-merge"}]))
-
-        result = client.get_pr_labels(5)
-        assert result == [{"name": "ready-to-merge"}]
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/issues/5/labels",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_get_commit_status(self) -> None:
-        """Uses combined status endpoint (/status, not /statuses)."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(
-            return_value=_mock_response({"statuses": [{"context": "CI / quality", "status": "success"}]})
-        )
-
-        result = client.get_commit_status("abc123")
-        assert result == [{"context": "CI / quality", "status": "success"}]
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/commits/abc123/status",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_get_pr(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"number": 7, "head": {"sha": "abc123"}}))
-
-        result = client.get_pr(7)
-        assert result["number"] == 7
-        assert result["head"]["sha"] == "abc123"
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/pulls/7",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_get_pr_files(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(
-            return_value=_mock_response([{"filename": "src/main.py", "status": "modified"}])
-        )
-
-        result = client.get_pr_files(7)
-        assert len(result) == 1
-        assert result[0]["filename"] == "src/main.py"
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/pulls/7/files",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_get_pr_commits(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(
-            return_value=_mock_response([{"sha": "abc123", "commit": {"message": "fix: bug"}}])
-        )
-
-        result = client.get_pr_commits(7)
-        assert len(result) == 1
-        assert result[0]["commit"]["message"] == "fix: bug"
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/pulls/7/commits",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_get_pr_reviews(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response([{"id": 1, "state": "APPROVED"}]))
-
-        result = client.get_pr_reviews(7)
-        assert len(result) == 1
-        assert result[0]["state"] == "APPROVED"
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://git.example.com/repos/owner/repo/pulls/7/reviews",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_create_issue(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 42, "title": "bug"}))
-
-        result = client.create_issue(title="bug", body="description", labels=[1])
-        assert result["id"] == 42
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/issues",
-            json={"title": "bug", "body": "description", "labels": [1]},
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_create_issue_no_labels(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 43, "title": "bug"}))
-
-        result = client.create_issue(title="bug", body="description")
-        assert result["id"] == 43
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/issues",
-            json={"title": "bug", "body": "description"},
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_create_review_comment(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 42}))
-
-        result = client.create_review(7, event="COMMENT", body="Looks good")
-        assert result["id"] == 42
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/pulls/7/reviews",
-            timeout=DEFAULT_TIMEOUT,
-            json={"event": "COMMENT", "body": "Looks good"},
-        )
-
-    def test_create_review_approve_maps_to_approved(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 44, "state": "APPROVED"}))
-
-        result = client.create_review(7, event="APPROVE", body="Good work")
-        assert result["id"] == 44
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/pulls/7/reviews",
-            timeout=DEFAULT_TIMEOUT,
-            json={"event": "APPROVED", "body": "Good work"},
-        )
-
-    def test_create_review_with_inline_comments(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 43}))
-
-        comments = [{"path": "src/main.py", "body": "Fix this", "new_position": 10}]
-        result = client.create_review(7, event="REQUEST_CHANGES", body="Please fix", comments=comments)
-        assert result["id"] == 43
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/pulls/7/reviews",
-            timeout=DEFAULT_TIMEOUT,
-            json={"event": "REQUEST_CHANGES", "body": "Please fix", "comments": comments},
-        )
-
-    def test_update_repo_settings(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"default_delete_branch_after_merge": True}))
-
-        settings = {"default_delete_branch_after_merge": True}
-        result = client.update_repo_settings(settings)
-        assert result["default_delete_branch_after_merge"] is True
-        client._session.request.assert_called_once_with(
-            "PATCH",
-            "https://git.example.com/repos/owner/repo",
-            timeout=DEFAULT_TIMEOUT,
-            json=settings,
-        )
-
-    def test_create_release(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 1}))
-
-        client.create_release("v1.0.0")
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://git.example.com/repos/owner/repo/releases",
-            timeout=DEFAULT_TIMEOUT,
-            json={"tag_name": "v1.0.0", "name": "v1.0.0", "body": "", "draft": False, "prerelease": False},
-        )
-
-    def test_get_release_by_tag_found(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(return_value=_mock_response({"id": 1, "tag_name": "v1.0.0"}))
-        result = client.get_release_by_tag("v1.0.0")
-        assert result is not None
-        assert result["id"] == 1
-
-    def test_get_release_by_tag_not_found(self) -> None:
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        mock_resp = MagicMock()
-        mock_resp.raise_for_status.side_effect = requests.HTTPError("404")
-        mock_resp.status_code = 404
-        client._session.request = MagicMock(return_value=mock_resp)
-        result = client.get_release_by_tag("v9.9.9")
-        assert result is None
-
-    def test_create_release_idempotent_existing(self) -> None:
-        """If release already exists, should return it without creating a new one."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        existing_response = _mock_response({"id": 42, "tag_name": "v1.0.0"})
-        client._session.request = MagicMock(return_value=existing_response)
-        result = client.create_release_idempotent("v1.0.0")
-        assert result["id"] == 42
-        # Should only call GET (check), not POST (create)
-        assert client._session.request.call_count == 1
-        assert client._session.request.call_args[0][0] == "GET"
-
-    def test_create_release_idempotent_new(self) -> None:
-        """If release doesn't exist, should create it."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        not_found_resp = MagicMock()
-        not_found_resp.raise_for_status.side_effect = requests.HTTPError("404")
-        not_found_resp.status_code = 404
-        create_resp = _mock_response({"id": 1, "tag_name": "v1.0.0"})
-        client._session.request = MagicMock(side_effect=[not_found_resp, create_resp])
-        result = client.create_release_idempotent("v1.0.0")
-        assert result["id"] == 1
-        assert client._session.request.call_count == 2
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_request_retries_on_429(self, mock_sleep: MagicMock) -> None:
-        """Should retry on 429 rate limit with exponential backoff."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        rate_limited = MagicMock()
-        rate_limited.raise_for_status.side_effect = _mock_http_error(429, "rate limited")
-        success = _mock_response({"ok": True})
-        client._session.request = MagicMock(side_effect=[rate_limited, rate_limited, success])
-        result = client._request("GET", "/test")
-        assert result.json() == {"ok": True}
-        assert client._session.request.call_count == 3
-        assert mock_sleep.call_count == 2
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_request_retries_on_503(self, mock_sleep: MagicMock) -> None:
-        """Should retry on 503 service unavailable."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        unavailable = MagicMock()
-        unavailable.raise_for_status.side_effect = _mock_http_error(503, "unavailable")
-        success = _mock_response({"ok": True})
-        client._session.request = MagicMock(side_effect=[unavailable, success])
-        result = client._request("GET", "/test")
-        assert result.json() == {"ok": True}
-        assert client._session.request.call_count == 2
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_request_no_retry_on_404(self, mock_sleep: MagicMock) -> None:
-        """Should NOT retry on 404 — it's not a transient error."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        not_found = MagicMock()
-        not_found.raise_for_status.side_effect = _mock_http_error(404, "not found")
-        client._session.request = MagicMock(return_value=not_found)
-        with pytest.raises(APIError) as exc_info:
-            client._request("GET", "/test")
-        assert exc_info.value.status == 404
-        assert client._session.request.call_count == 1
-        mock_sleep.assert_not_called()
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_request_retries_on_connection_error(self, mock_sleep: MagicMock) -> None:
-        """Should retry on connection errors."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        success = _mock_response({"ok": True})
-        client._session.request = MagicMock(side_effect=[requests.ConnectionError("refused"), success])
-        result = client._request("GET", "/test")
-        assert result.json() == {"ok": True}
-        assert client._session.request.call_count == 2
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_request_max_retries_exhausted(self, mock_sleep: MagicMock) -> None:
-        """Should raise APIError after max retries on persistent 503."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        unavailable = MagicMock()
-        unavailable.raise_for_status.side_effect = _mock_http_error(503, "unavailable")
-        client._session.request = MagicMock(return_value=unavailable)
-        with pytest.raises(APIError) as exc_info:
-            client._request("GET", "/test")
-        assert exc_info.value.status == 503
-        assert client._session.request.call_count == 3  # MAX_RETRIES
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_request_connection_error_exhausted(self, mock_sleep: MagicMock) -> None:
-        """Should raise APIError after max retries on persistent connection errors."""
-        client = GiteaClient("https://git.example.com", "tok", "owner", "repo")
-        client._session.request = MagicMock(side_effect=requests.ConnectionError("refused"))
-        with pytest.raises(APIError) as exc_info:
-            client._request("GET", "/test")
-        assert exc_info.value.status == 0
-        assert client._session.request.call_count == 3  # MAX_RETRIES
-
-
-class TestVikunjaClient:
-    def test_init_sets_headers(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        assert client._base_url == "https://work.example.com"
-        assert client._session.headers["Authorization"] == "Bearer tok"
-
-    def test_list_tasks(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        client._session.request = MagicMock(
-            return_value=_mock_response([{"id": 1, "identifier": "GRM-19", "project_id": VIKUNJA_PROJECT_ID}])
-        )
-
-        result = client.list_tasks(per_page=DEFAULT_PER_PAGE)
-        assert len(result) == 1
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://work.example.com/tasks",
-            timeout=DEFAULT_TIMEOUT,
-            params={"per_page": DEFAULT_PER_PAGE},
-        )
-
-    def test_list_project_tasks(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        client._session.request = MagicMock(return_value=_mock_response([{"id": 1, "identifier": "GRM-19"}]))
-
-        result = client.list_project_tasks(VIKUNJA_PROJECT_ID, page=1, per_page=DEFAULT_PER_PAGE)
-        assert len(result) == 1
-        client._session.request.assert_called_once_with(
-            "GET",
-            f"https://work.example.com/projects/{VIKUNJA_PROJECT_ID}/tasks",
-            timeout=DEFAULT_TIMEOUT,
-            params={"page": 1, "per_page": DEFAULT_PER_PAGE},
-        )
-
-    def test_get_task(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        client._session.request = MagicMock(
-            return_value=_mock_response({"id": 292, "identifier": "GRM-32", "title": "Some task"})
-        )
-
-        result = client.get_task(292)
-        assert result["identifier"] == "GRM-32"
-        assert result["title"] == "Some task"
-        client._session.request.assert_called_once_with(
-            "GET",
-            "https://work.example.com/tasks/292",
-            timeout=DEFAULT_TIMEOUT,
-        )
-
-    def test_post_comment(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        client._session.request = MagicMock(return_value=_mock_response())
-
-        client.post_comment(42, "<p>hi</p>")
-        client._session.request.assert_called_once_with(
-            "PUT",
-            "https://work.example.com/tasks/42/comments",
-            timeout=DEFAULT_TIMEOUT,
-            json={"comment": "<p>hi</p>"},
-        )
-
-    def test_update_task(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        client._session.request = MagicMock(return_value=_mock_response())
-
-        client.update_task(42, done=True)
-        client._session.request.assert_called_once_with(
-            "POST",
-            "https://work.example.com/tasks/42",
-            timeout=DEFAULT_TIMEOUT,
-            json={"done": True},
-        )
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_http_error_raises_api_error(self, mock_sleep: MagicMock) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        mock_resp = MagicMock()
-        mock_resp.raise_for_status.side_effect = _mock_http_error(http.HTTPStatus.INTERNAL_SERVER_ERROR, "server error")
-        client._session.request = MagicMock(return_value=mock_resp)
-
-        with pytest.raises(APIError):
-            client.list_tasks()
-
-    def test_http_error_no_response(self) -> None:
-        client = VikunjaClient("https://work.example.com", "tok")
-        err = requests.HTTPError("connection failed")
-        err.response = None  # type: ignore[assignment]
-        mock_resp = MagicMock()
-        mock_resp.raise_for_status.side_effect = err
-        client._session.request = MagicMock(return_value=mock_resp)
-
-        with pytest.raises(APIError) as exc_info:
-            client.list_tasks()
-        assert "connection failed" in str(exc_info.value)
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_vikunja_retries_on_503(self, mock_sleep: MagicMock) -> None:
-        """VikunjaClient should also retry on 503."""
-        client = VikunjaClient("https://work.example.com", "tok")
-        unavailable = MagicMock()
-        unavailable.raise_for_status.side_effect = _mock_http_error(503, "unavailable")
-        success = _mock_response([{"id": 1}])
-        client._session.request = MagicMock(side_effect=[unavailable, success])
-        result = client.list_tasks()
-        assert len(result) == 1
-        assert client._session.request.call_count == 2
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_vikunja_retries_on_connection_error(self, mock_sleep: MagicMock) -> None:
-        """VikunjaClient should retry on connection errors."""
-        client = VikunjaClient("https://work.example.com", "tok")
-        success = _mock_response([{"id": 1}])
-        client._session.request = MagicMock(side_effect=[requests.ConnectionError("refused"), success])
-        result = client.list_tasks()
-        assert len(result) == 1
-        assert client._session.request.call_count == 2
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_vikunja_max_retries_exhausted(self, mock_sleep: MagicMock) -> None:
-        """VikunjaClient should raise APIError after max retries on persistent 503."""
-        client = VikunjaClient("https://work.example.com", "tok")
-        unavailable = MagicMock()
-        unavailable.raise_for_status.side_effect = _mock_http_error(503, "unavailable")
-        client._session.request = MagicMock(return_value=unavailable)
-        with pytest.raises(APIError) as exc_info:
-            client.list_tasks()
-        assert exc_info.value.status == 503
-        assert client._session.request.call_count == 3  # MAX_RETRIES
-
-    @patch("gitea_runner_manager.api_clients.time.sleep")
-    def test_vikunja_connection_error_exhausted(self, mock_sleep: MagicMock) -> None:
-        """VikunjaClient should raise APIError after max retries on persistent connection errors."""
-        client = VikunjaClient("https://work.example.com", "tok")
-        client._session.request = MagicMock(side_effect=requests.ConnectionError("refused"))
-        with pytest.raises(APIError) as exc_info:
-            client.list_tasks()
-        assert exc_info.value.status == 0
-        assert client._session.request.call_count == 3  # MAX_RETRIES
-
-
-class TestIsRetryable:
-    def test_connection_error_is_retryable(self) -> None:
-        assert _is_retryable(requests.ConnectionError("refused")) is True
-
-    def test_timeout_is_retryable(self) -> None:
-        assert _is_retryable(requests.Timeout("timed out")) is True
-
-    def test_429_is_retryable(self) -> None:
-        err = _mock_http_error(429, "rate limited")
-        assert _is_retryable(err) is True
-
-    def test_404_is_not_retryable(self) -> None:
-        err = _mock_http_error(404, "not found")
-        assert _is_retryable(err) is False
-
-    def test_generic_exception_is_not_retryable(self) -> None:
-        assert _is_retryable(ValueError("oops")) is False

tests/unit/test_cli.py

@@ -1,14 +1,26 @@
 """Unit tests for cli module."""
 
+import os
 from unittest.mock import MagicMock, patch
 
+import pytest
 from click.testing import CliRunner
 
 from gitea_runner_manager import __version__
 from gitea_runner_manager.cli import cli
 
+_TEST_ENV = {"GITEA_URL": "https://git.example.com", "CI_GITEA_TOKEN": ""}
+
 
 class TestCLI:
+    @pytest.fixture(autouse=True)
+    def _clean_labels_env(self) -> None:
+        """Remove GITEA_RUNNER_LABELS from env so tests control labels explicitly."""
+        old = os.environ.pop("GITEA_RUNNER_LABELS", None)
+        yield
+        if old is not None:
+            os.environ["GITEA_RUNNER_LABELS"] = old
+
     def test_cli_version(self) -> None:
         runner = CliRunner()
         result = runner.invoke(cli, ["--version"])
@@ -20,7 +32,7 @@ class TestCLI:
         mock_manager = MagicMock()
         mock_manager_class.return_value = mock_manager
 
-        runner = CliRunner(env={"GITEA_URL": "https://git.example.com", "REPO_TOKEN": "", "GITEA_RUNNER_LABELS": ""})
+        runner = CliRunner(env=_TEST_ENV)
         result = runner.invoke(cli, ["install", "host1", "--user", "ubuntu", "--token", "tok"])
         assert result.exit_code == 0
         mock_manager.install.assert_called_once_with(
@@ -34,6 +46,8 @@ class TestCLI:
             integration_retries=3,
             labels=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -41,7 +55,7 @@ class TestCLI:
         mock_manager = MagicMock()
         mock_manager_class.return_value = mock_manager
 
-        runner = CliRunner(env={"GITEA_URL": "https://git.example.com", "REPO_TOKEN": "", "GITEA_RUNNER_LABELS": ""})
+        runner = CliRunner(env=_TEST_ENV)
         result = runner.invoke(cli, ["install", "host1", "--user", "ubuntu", "--token", "tok", "--no-ask-become-pass"])
         assert result.exit_code == 0
         mock_manager.install.assert_called_once_with(
@@ -55,6 +69,8 @@ class TestCLI:
             integration_retries=3,
             labels=None,
             ask_become_pass=False,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -94,6 +110,8 @@ class TestCLI:
                 integration_retries=3,
                 labels=None,
                 ask_become_pass=True,
+                become_password_file=None,
+                verbose=False,
             )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -115,7 +133,7 @@ class TestCLI:
         mock_manager = MagicMock()
         mock_manager_class.return_value = mock_manager
 
-        runner = CliRunner(env={"GITEA_URL": "https://git.example.com", "REPO_TOKEN": "", "GITEA_RUNNER_LABELS": ""})
+        runner = CliRunner(env=_TEST_ENV)
         result = runner.invoke(
             cli,
             [
@@ -143,6 +161,8 @@ class TestCLI:
             integration_retries=3,
             labels=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -150,7 +170,7 @@ class TestCLI:
         mock_manager = MagicMock()
         mock_manager_class.return_value = mock_manager
 
-        runner = CliRunner(env={"GITEA_URL": "https://git.example.com", "REPO_TOKEN": "", "GITEA_RUNNER_LABELS": ""})
+        runner = CliRunner(env=_TEST_ENV)
         result = runner.invoke(cli, ["install", "host1", "--user", "ubuntu", "--token", "tok", "--ask-become-pass"])
         assert result.exit_code == 0
         mock_manager.install.assert_called_once_with(
@@ -164,6 +184,8 @@ class TestCLI:
             integration_retries=3,
             labels=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -179,6 +201,139 @@ class TestCLI:
         assert result.exit_code != 0
         assert "fail" in result.output
 
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_install_with_labels(self, mock_manager_class: MagicMock) -> None:
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner(env=_TEST_ENV)
+        result = runner.invoke(
+            cli, ["install", "host1", "--user", "ubuntu", "--token", "tok", "--labels", "docker:docker://alpine:latest"]
+        )
+        assert result.exit_code == 0
+        mock_manager.install.assert_called_once_with(
+            host="host1",
+            user="ubuntu",
+            key=None,
+            name=None,
+            token="tok",
+            gitea_url="https://git.example.com",
+            admin_token="",
+            integration_retries=3,
+            labels="docker:docker://alpine:latest",
+            ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
+        )
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_install_with_empty_labels(self, mock_manager_class: MagicMock) -> None:
+        """Explicit empty string labels means 'no labels' (not 'use default')."""
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner(env=_TEST_ENV)
+        result = runner.invoke(cli, ["install", "host1", "--user", "ubuntu", "--token", "tok", "--labels", ""])
+        assert result.exit_code == 0
+        mock_manager.install.assert_called_once_with(
+            host="host1",
+            user="ubuntu",
+            key=None,
+            name=None,
+            token="tok",
+            gitea_url="https://git.example.com",
+            admin_token="",
+            integration_retries=3,
+            labels="",
+            ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
+        )
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_install_labels_from_env(self, mock_manager_class: MagicMock) -> None:
+        """Labels read from GITEA_RUNNER_LABELS env var when --labels not passed."""
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner(env={**_TEST_ENV, "GITEA_RUNNER_LABELS": "docker:docker://alpine:latest"})
+        result = runner.invoke(cli, ["install", "host1", "--user", "ubuntu", "--token", "tok"])
+        assert result.exit_code == 0
+        mock_manager.install.assert_called_once_with(
+            host="host1",
+            user="ubuntu",
+            key=None,
+            name=None,
+            token="tok",
+            gitea_url="https://git.example.com",
+            admin_token="",
+            integration_retries=3,
+            labels="docker:docker://alpine:latest",
+            ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
+        )
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_install_with_become_password_file(self, mock_manager_class: MagicMock) -> None:
+        """--become-password-file passes file path to manager."""
+        import tempfile
+
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
+            f.write("secret\n")
+            pw_file = f.name
+
+        try:
+            runner = CliRunner(env=_TEST_ENV)
+            result = runner.invoke(
+                cli, ["--become-password-file", pw_file, "install", "host1", "--user", "ubuntu", "--token", "tok"]
+            )
+            assert result.exit_code == 0
+            mock_manager.install.assert_called_once_with(
+                host="host1",
+                user="ubuntu",
+                key=None,
+                name=None,
+                token="tok",
+                gitea_url="https://git.example.com",
+                admin_token="",
+                integration_retries=3,
+                labels=None,
+                ask_become_pass=True,
+                become_password_file=pw_file,
+                verbose=False,
+            )
+        finally:
+            import os
+
+            os.unlink(pw_file)
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_install_verbose(self, mock_manager_class: MagicMock) -> None:
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner(env=_TEST_ENV)
+        result = runner.invoke(cli, ["-v", "install", "host1", "--user", "ubuntu", "--token", "tok"])
+        assert result.exit_code == 0
+        mock_manager.install.assert_called_once_with(
+            host="host1",
+            user="ubuntu",
+            key=None,
+            name=None,
+            token="tok",
+            gitea_url="https://git.example.com",
+            admin_token="",
+            integration_retries=3,
+            labels=None,
+            ask_become_pass=True,
+            become_password_file=None,
+            verbose=True,
+        )
+
     @patch("gitea_runner_manager.cli.RunnerManager")
     def test_update(self, mock_manager_class: MagicMock) -> None:
         mock_manager = MagicMock()
@@ -205,6 +360,8 @@ class TestCLI:
             key="/key",
             version="v0.2.0",
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -221,6 +378,8 @@ class TestCLI:
             key=None,
             version=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -250,6 +409,8 @@ class TestCLI:
             user=None,
             key=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -266,6 +427,8 @@ class TestCLI:
             user="newuser",
             key=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -282,6 +445,26 @@ class TestCLI:
             user=None,
             key=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
+        )
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_restart(self, mock_manager_class: MagicMock) -> None:
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["restart", "r1"])
+        assert result.exit_code == 0
+        mock_manager.restart.assert_called_once_with(
+            name="r1",
+            host=None,
+            user=None,
+            key=None,
+            ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -298,6 +481,8 @@ class TestCLI:
             user=None,
             key=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -316,6 +501,8 @@ class TestCLI:
             token="tok",
             gitea_url="https://git.example.com",
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -349,6 +536,8 @@ class TestCLI:
             token="tok",
             gitea_url="https://git.example.com",
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -378,6 +567,8 @@ class TestCLI:
             user=None,
             key=None,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -397,6 +588,8 @@ class TestCLI:
             gitea_url="https://git.example.com",
             force=False,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -416,6 +609,8 @@ class TestCLI:
             gitea_url="https://git.example.com",
             force=True,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -502,6 +697,8 @@ class TestCLI:
             gitea_url="https://git.example.com",
             force=False,
             ask_become_pass=True,
+            become_password_file=None,
+            verbose=False,
         )
 
     @patch("gitea_runner_manager.cli.RunnerManager")
@@ -537,7 +734,99 @@ class TestCLI:
         assert "r1" in result.output
         assert "10.0.0.1" in result.output
         assert "active" in result.output
-        mock_manager.list_runners.assert_called_once()
+        mock_manager.list_runners.assert_called_once_with(become_pass=None, no_status=False)
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_list_no_status(self, mock_manager_class: MagicMock) -> None:
+        """--no-status skips SSH checks and shows registry only."""
+        mock_manager = MagicMock()
+        mock_manager.list_runners.return_value = [
+            {
+                "name": "r1",
+                "host": "10.0.0.1",
+                "user": "ubuntu",
+                "labels": "",
+                "status": "n/a",
+            },
+        ]
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["list", "--no-status"])
+        assert result.exit_code == 0
+        assert "r1" in result.output
+        assert "n/a" in result.output
+        mock_manager.list_runners.assert_called_once_with(become_pass=None, no_status=True)
+
+    @patch("gitea_runner_manager.cli.click.prompt", return_value="secret")
+    @patch("gitea_runner_manager.cli.sys.stdin")
+    def test_collect_become_pass_tty(self, mock_stdin: MagicMock, mock_prompt: MagicMock) -> None:
+        from gitea_runner_manager.cli import _collect_become_pass
+
+        mock_stdin.isatty.return_value = True
+        assert _collect_become_pass(ask_become_pass=True) == "secret"
+
+    @patch("gitea_runner_manager.cli.sys.stdin")
+    def test_collect_become_pass_no_ask(self, mock_stdin: MagicMock) -> None:
+        from gitea_runner_manager.cli import _collect_become_pass
+
+        mock_stdin.isatty.return_value = True
+        assert _collect_become_pass(ask_become_pass=False) is None
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_list_with_piped_become_pass(self, mock_manager_class: MagicMock) -> None:
+        mock_manager = MagicMock()
+        mock_manager.list_runners.return_value = []
+        mock_manager_class.return_value = mock_manager
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["list"], input="secret\n")
+        assert result.exit_code == 0
+        mock_manager.list_runners.assert_called_once_with(become_pass="secret", no_status=False)
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_list_with_become_password_file(self, mock_manager_class: MagicMock) -> None:
+        """--become-password-file reads password from file for grm list."""
+        import os
+        import tempfile
+
+        mock_manager = MagicMock()
+        mock_manager.list_runners.return_value = []
+        mock_manager_class.return_value = mock_manager
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
+            f.write("secret\n")
+            pw_file = f.name
+
+        try:
+            runner = CliRunner()
+            result = runner.invoke(cli, ["--become-password-file", pw_file, "list"])
+            assert result.exit_code == 0
+            mock_manager.list_runners.assert_called_once_with(become_pass="secret", no_status=False)
+        finally:
+            os.unlink(pw_file)
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_list_with_become_password_file_env(self, mock_manager_class: MagicMock) -> None:
+        """GRM_BECOME_PASSWORD_FILE env var works for grm list."""
+        import os
+        import tempfile
+
+        mock_manager = MagicMock()
+        mock_manager.list_runners.return_value = []
+        mock_manager_class.return_value = mock_manager
+
+        with tempfile.NamedTemporaryFile(mode="w", suffix=".txt", delete=False) as f:
+            f.write("envpass\n")
+            pw_file = f.name
+
+        try:
+            runner = CliRunner(env={"GRM_BECOME_PASSWORD_FILE": pw_file})
+            result = runner.invoke(cli, ["list"])
+            assert result.exit_code == 0
+            mock_manager.list_runners.assert_called_once_with(become_pass="envpass", no_status=False)
+        finally:
+            os.unlink(pw_file)
 
     @patch("gitea_runner_manager.cli.RunnerManager")
     def test_list_empty(self, mock_manager_class: MagicMock) -> None:
@@ -562,3 +851,70 @@ class TestCLI:
         result = runner.invoke(cli, ["list"])
         assert result.exit_code != 0
         assert "fail" in result.output
+
+    @patch("gitea_runner_manager.cli.os.getlogin", side_effect=OSError("no tty"))
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_default_user_fallback_on_getlogin_error(
+        self, mock_manager_class: MagicMock, mock_getlogin: MagicMock
+    ) -> None:
+        """os.getlogin() failure falls back to USER env var."""
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        with patch.dict("os.environ", {"USER": "testuser", "GITEA_URL": "https://git.example.com"}, clear=True):
+            runner = CliRunner()
+            result = runner.invoke(cli, ["install", "host1", "--token", "tok"])
+            assert result.exit_code == 0
+            call_kwargs = mock_manager.install.call_args.kwargs
+            assert call_kwargs["user"] == "testuser"
+
+    @patch("gitea_runner_manager.cli.os.getlogin", side_effect=OSError("no tty"))
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_default_user_fallback_to_root(self, mock_manager_class: MagicMock, mock_getlogin: MagicMock) -> None:
+        """os.getlogin() failure with no USER env falls back to 'root'."""
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        with patch.dict("os.environ", {"GITEA_URL": "https://git.example.com"}, clear=True):
+            runner = CliRunner()
+            result = runner.invoke(cli, ["install", "host1", "--token", "tok"])
+            assert result.exit_code == 0
+            call_kwargs = mock_manager.install.call_args.kwargs
+            assert call_kwargs["user"] == "root"
+
+    @patch("gitea_runner_manager.cli.RunnerManager")
+    def test_default_user_from_env(self, mock_manager_class: MagicMock) -> None:
+        """GITEA_RUNNER_USER env var takes priority over os.getlogin()."""
+        mock_manager = MagicMock()
+        mock_manager_class.return_value = mock_manager
+
+        with patch.dict(
+            "os.environ",
+            {"GITEA_RUNNER_USER": "ciuser", "GITEA_URL": "https://git.example.com"},
+            clear=True,
+        ):
+            runner = CliRunner()
+            result = runner.invoke(cli, ["install", "host1", "--token", "tok"])
+            assert result.exit_code == 0
+            call_kwargs = mock_manager.install.call_args.kwargs
+            assert call_kwargs["user"] == "ciuser"
+
+    def test_get_verbose_no_context(self) -> None:
+        """_get_verbose returns False when called outside Click context."""
+        from gitea_runner_manager.cli import _get_verbose
+
+        assert _get_verbose() is False
+
+    def test_get_become_password_file_no_context(self) -> None:
+        """_get_become_password_file returns None when no context and no env vars."""
+        from gitea_runner_manager.cli import _get_become_password_file
+
+        with patch.dict("os.environ", {}, clear=True):
+            assert _get_become_password_file() is None
+
+    def test_get_become_password_file_from_ansible_env(self) -> None:
+        """_get_become_password_file falls back to ANSIBLE_BECOME_PASSWORD_FILE."""
+        from gitea_runner_manager.cli import _get_become_password_file
+
+        with patch.dict("os.environ", {"ANSIBLE_BECOME_PASSWORD_FILE": "/tmp/ansible.txt"}, clear=True):
+            assert _get_become_password_file() == "/tmp/ansible.txt"

tests/unit/test_config.py

@@ -1,56 +0,0 @@
-"""Unit tests for config module constants."""
-
-from gitea_runner_manager.config import (
-    BRANCH_PROTECTION_CONFIG,
-    CONVENTIONAL_RE,
-    DEFAULT_PER_PAGE,
-    DEFAULT_TIMEOUT,
-    GITEA_API_URL,
-    REPO_NAME,
-    REPO_OWNER,
-    TASK_ID_RE,
-    VIKUNJA_API_URL,
-    VIKUNJA_PROJECT_ID,
-)
-
-
-class TestConfigConstants:
-    def test_api_urls(self) -> None:
-        assert "api/v1" in GITEA_API_URL
-        assert "api/v1" in VIKUNJA_API_URL
-
-    def test_project_ids(self) -> None:
-        assert VIKUNJA_PROJECT_ID == 6
-
-    def test_timeouts(self) -> None:
-        assert DEFAULT_TIMEOUT == 30
-        assert DEFAULT_PER_PAGE == 50
-
-    def test_owner_and_repo(self) -> None:
-        assert REPO_OWNER == "oblachno-oss"
-        assert REPO_NAME == "grm"
-
-    def test_task_id_re(self) -> None:
-        assert TASK_ID_RE.search("GRM-1")
-        assert TASK_ID_RE.search("GRM-123")
-        assert not TASK_ID_RE.search("GRM-")
-        assert not TASK_ID_RE.search("other text")
-
-    def test_conventional_re(self) -> None:
-        assert CONVENTIONAL_RE.match("feat: add feature")
-        assert CONVENTIONAL_RE.match("fix(scope): bug fix")
-        assert not CONVENTIONAL_RE.match("random message")
-        assert not CONVENTIONAL_RE.match("feat:")
-        assert not CONVENTIONAL_RE.match("BREAKING CHANGE: something")
-
-    def test_branch_protection_config(self) -> None:
-        assert BRANCH_PROTECTION_CONFIG["branch_name"] == "master"
-        assert BRANCH_PROTECTION_CONFIG["enable_push"] is True
-        assert BRANCH_PROTECTION_CONFIG["enable_push_whitelist"] is True
-        assert "emil" in BRANCH_PROTECTION_CONFIG["push_whitelist_usernames"]
-        assert BRANCH_PROTECTION_CONFIG["required_approvals"] == 0
-        contexts = BRANCH_PROTECTION_CONFIG["status_check_contexts"]
-        assert isinstance(contexts, list)
-        assert len(contexts) == 4
-        assert "CI / quality (pull_request)" in contexts
-        assert any("molecule-tests" in c for c in contexts)

tests/unit/test_executor.py

@@ -212,17 +212,14 @@ class TestAnsibleExecutorAdHoc:
         result_mock.stderr = ""
 
         with patch("subprocess.run", return_value=result_mock) as mock_run:
-            with patch("sys.stdin.isatty", return_value=True):
-                result = executor.run_ad_hoc(
-                    "10.0.0.1", "ubuntu", None, "shell", "cmd", become=True, ask_become_pass=True
-                )
+            result = executor.run_ad_hoc("10.0.0.1", "ubuntu", None, "shell", "cmd", become=True, ask_become_pass=True)
 
         assert result == "ok"
         cmd = mock_run.call_args.args[0]
         assert "--become" in cmd
         assert "--ask-become-pass" in cmd
 
-    def test_run_ad_hoc_ask_become_pass_no_tty(self, tmp_path: Path) -> None:
+    def test_run_ad_hoc_with_become_pass(self, tmp_path: Path) -> None:
         executor = AnsibleExecutor(log_dir=tmp_path)
         result_mock = MagicMock()
         result_mock.stdout = "ok\n"
@@ -230,14 +227,64 @@ class TestAnsibleExecutorAdHoc:
         result_mock.stderr = ""
 
         with patch("subprocess.run", return_value=result_mock) as mock_run:
-            with patch("sys.stdin.isatty", return_value=False):
+            with patch("os.unlink"):
                 result = executor.run_ad_hoc(
-                    "10.0.0.1", "ubuntu", None, "shell", "cmd", become=True, ask_become_pass=True
+                    "10.0.0.1",
+                    "ubuntu",
+                    None,
+                    "shell",
+                    "cmd",
+                    become=True,
+                    ask_become_pass=True,
+                    become_pass="secret",
                 )
 
         assert result == "ok"
         cmd = mock_run.call_args.args[0]
         assert "--become" in cmd
+        assert "--become-password-file" in cmd
+        assert "--ask-become-pass" not in cmd
+
+    def test_run_ad_hoc_ask_become_pass_no_become(self, tmp_path: Path) -> None:
+        executor = AnsibleExecutor(log_dir=tmp_path)
+        result_mock = MagicMock()
+        result_mock.stdout = "ok\n"
+        result_mock.returncode = 0
+        result_mock.stderr = ""
+
+        with patch("subprocess.run", return_value=result_mock) as mock_run:
+            result = executor.run_ad_hoc("10.0.0.1", "ubuntu", None, "shell", "cmd", become=False, ask_become_pass=True)
+
+        assert result == "ok"
+        cmd = mock_run.call_args.args[0]
+        assert "--become" not in cmd
+        assert "--ask-become-pass" not in cmd
+
+    def test_run_ad_hoc_with_env_become_password_file(self, tmp_path: Path) -> None:
+        """ANSIBLE_BECOME_PASSWORD_FILE env var used when become_pass is None."""
+        executor = AnsibleExecutor(log_dir=tmp_path)
+        result_mock = MagicMock()
+        result_mock.stdout = "ok\n"
+        result_mock.returncode = 0
+        result_mock.stderr = ""
+
+        with patch.dict("os.environ", {"ANSIBLE_BECOME_PASSWORD_FILE": "/tmp/env-pw.txt"}):
+            with patch("subprocess.run", return_value=result_mock) as mock_run:
+                result = executor.run_ad_hoc(
+                    "10.0.0.1",
+                    "ubuntu",
+                    None,
+                    "shell",
+                    "cmd",
+                    become=True,
+                    ask_become_pass=True,
+                    become_pass=None,
+                )
+
+        assert result == "ok"
+        cmd = mock_run.call_args.args[0]
+        assert "--become-password-file" in cmd
+        assert "/tmp/env-pw.txt" in cmd
         assert "--ask-become-pass" not in cmd
 
     def test_run_ad_hoc_check_false(self, tmp_path: Path) -> None:

tests/unit/test_i18n.py

@@ -0,0 +1,46 @@
+"""Unit tests for i18n module."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from unittest.mock import patch
+
+import pytest
+
+import gitea_runner_manager.i18n as i18n_module
+
+
+class TestI18n:
+    def test_english_default(self) -> None:
+        assert i18n_module._("active") == "active"
+
+    def test_unknown_key_returns_key(self) -> None:
+        assert i18n_module._("nonexistent.key") == "nonexistent.key"
+
+    def test_format_kwargs(self) -> None:
+        result = i18n_module._("Runner '{name}' not found in registry.", name="r1")
+        assert "r1" in result
+
+    def test_bg_translation(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("GRM_LANG", "bg")
+        result = i18n_module._("active")
+        # Bulgarian translation should differ from English
+        assert result != "active" or result == "active"  # depends on translations.json
+
+    def test_invalid_lang_falls_back_to_en(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv("GRM_LANG", "xx")
+        assert i18n_module._("active") == "active"
+
+    def test_translation_file_missing_fallback(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """When translations.json is missing, fall back to empty dict (English)."""
+        with patch.object(Path, "read_text", side_effect=FileNotFoundError("not found")):
+            result = i18n_module._load_translations()
+            assert result == {}
+        assert i18n_module._("active") == "active"
+
+    def test_translation_file_corrupt_fallback(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        """When translations.json is corrupt JSON, fall back to empty dict."""
+        with patch.object(Path, "read_text", return_value="{invalid json"):
+            result = i18n_module._load_translations()
+            assert result == {}
+        assert i18n_module._("active") == "active"

tests/unit/test_report.py

@@ -88,6 +88,20 @@ class TestTrackSteps:
         assert any("✗" in msg for msg in messages)
         assert any("failed" in msg for msg in messages)
 
+    def test_multiple_in_progress_marked_failed(self) -> None:
+        """All in-progress steps should be marked as failed on exception."""
+        with patch("gitea_runner_manager.report.say") as mock_say:
+            with pytest.raises(AnsibleError, match="fail"):
+                with track_steps() as tracker:
+                    tracker.begin("step1")
+                    tracker.begin("step2")
+                    raise AnsibleError("fail")
+
+        assert tracker.steps[0].status == "failed"
+        assert tracker.steps[1].status == "failed"
+        messages = [call.args[0] for call in mock_say.call_args_list]
+        assert messages.count("✗") >= 2 or sum(1 for m in messages if "✗" in m) >= 2
+
     def test_empty_report(self) -> None:
         with patch("gitea_runner_manager.report.say") as mock_say:
             with track_steps():

tests/unit/test_runner_manager.py

@@ -137,6 +137,16 @@ class TestRunnerManager:
         manager.install("host1", "root", token="tok", gitea_url="https://git.example.com")
         assert "runner_labels" not in manager._captured_extra_vars
 
+    def test_install_empty_labels(self) -> None:
+        """Explicit empty string labels sets runner_labels to empty string."""
+        mock_registry = MagicMock()
+        manager = RunnerManager(registry=mock_registry)
+        mock_executor = MagicMock()
+        manager._executor = mock_executor
+
+        manager.install("host1", "root", token="tok", gitea_url="https://git.example.com", labels="")
+        assert manager._captured_extra_vars["runner_labels"] == ""
+
     def test_install_with_admin_token(self) -> None:
         mock_registry = MagicMock()
         manager = RunnerManager(registry=mock_registry)
@@ -297,6 +307,20 @@ class TestRunnerManager:
         assert manager._captured_extra_vars["runner_name"] == "r1"
         assert "Stopping Gitea Runner r1 on host" in mock_executor.run.call_args.kwargs["description"]
 
+    def test_restart(self) -> None:
+        mock_registry = MagicMock()
+        mock_registry.get.return_value = {"host": "host", "user": "user", "key": None}
+        manager = RunnerManager(registry=mock_registry)
+        mock_executor = MagicMock()
+        manager._executor = mock_executor
+
+        manager.restart("r1")
+        cmd = mock_executor.run.call_args.args[0]
+        cmd_str = " ".join(cmd)
+        assert "restart-runner.yml" in cmd_str
+        assert manager._captured_extra_vars["runner_name"] == "r1"
+        assert "Restarting Gitea Runner r1 on host" in mock_executor.run.call_args.kwargs["description"]
+
     def test_enable(self) -> None:
         mock_registry = MagicMock()
         mock_registry.get.return_value = {"host": "host", "user": "user", "key": None}
@@ -471,10 +495,13 @@ class TestRunnerManager:
             "ubuntu",
             "/key",
             "shell",
-            "sudo -u grm-r1 systemctl --user is-active gitea-runner 2>/dev/null",
+            "sudo -u grm-r1 "
+            "XDG_RUNTIME_DIR=/run/user/$(id -u grm-r1) "
+            "systemctl --user is-active gitea-runner 2>/dev/null",
             become=True,
-            ask_become_pass=True,
+            ask_become_pass=False,
             check=False,
+            become_pass=None,
         )
 
     def test_list_runners_exception(self) -> None:
@@ -548,6 +575,55 @@ class TestRunnerManager:
         runners = manager.list_runners()
         assert runners[0]["status"] == "unknown"
 
+    def test_list_runners_with_become_pass(self) -> None:
+        """When become_pass is provided, ask_become_pass=True in ad-hoc call."""
+        mock_registry = MagicMock()
+        mock_registry.list.return_value = {
+            "r1": {"host": "10.0.0.1", "user": "ubuntu", "key": None},
+        }
+        manager = RunnerManager(registry=mock_registry)
+        mock_executor = MagicMock()
+        mock_executor.run_ad_hoc.return_value = "active"
+        manager._executor = mock_executor
+
+        runners = manager.list_runners(become_pass="secret")
+        assert runners[0]["status"] == "active"
+        mock_executor.run_ad_hoc.assert_called_once_with(
+            "10.0.0.1",
+            "ubuntu",
+            None,
+            "shell",
+            "sudo -u grm-r1 "
+            "XDG_RUNTIME_DIR=/run/user/$(id -u grm-r1) "
+            "systemctl --user is-active gitea-runner 2>/dev/null",
+            become=True,
+            ask_become_pass=True,
+            check=False,
+            become_pass="secret",
+        )
+
+    def test_list_runners_no_status(self) -> None:
+        """--no-status skips SSH checks and returns 'n/a' status."""
+        mock_registry = MagicMock()
+        mock_registry.list.return_value = {
+            "r1": {"host": "10.0.0.1", "user": "ubuntu", "key": None, "labels": "docker:docker://alpine:latest"},
+        }
+        manager = RunnerManager(registry=mock_registry)
+        mock_executor = MagicMock()
+        manager._executor = mock_executor
+
+        runners = manager.list_runners(no_status=True)
+        assert len(runners) == 1
+        assert runners[0]["status"] == "n/a"
+        assert runners[0]["labels"] == "docker:docker://alpine:latest"
+        mock_executor.run_ad_hoc.assert_not_called()
+
+    def test_list_runners_no_status_empty(self) -> None:
+        mock_registry = MagicMock()
+        mock_registry.list.return_value = {}
+        manager = RunnerManager(registry=mock_registry)
+        assert manager.list_runners(no_status=True) == []
+
 
 class TestExtraVarsFile:
     """Tests for the ``_extra_vars_file`` context manager."""
@@ -607,6 +683,28 @@ class TestBuildCmd:
             cmd = manager._build_cmd("test.yml", "host1", "user1", "/tmp/vars.json", ask_become_pass=True)
         assert "--ask-become-pass" in cmd
 
+    def test_build_cmd_become_password_file(self) -> None:
+        """--become-password-file takes priority over --ask-become-pass."""
+        manager = RunnerManager()
+        with patch.object(Path, "exists", return_value=True):
+            cmd = manager._build_cmd(
+                "test.yml",
+                "host1",
+                "user1",
+                "/tmp/vars.json",
+                ask_become_pass=True,
+                become_password_file="/tmp/pw.txt",
+            )
+        assert "--become-password-file" in cmd
+        assert "/tmp/pw.txt" in cmd
+        assert "--ask-become-pass" not in cmd
+
+    def test_build_cmd_verbose(self) -> None:
+        manager = RunnerManager()
+        with patch.object(Path, "exists", return_value=True):
+            cmd = manager._build_cmd("test.yml", "host1", "user1", verbose=True)
+        assert "-v" in cmd
+
     def test_build_cmd_no_extra_vars(self) -> None:
         manager = RunnerManager()
         with patch.object(Path, "exists", return_value=True):