CI

.gitea/workflows/ci.yml

@@ -1,7 +1,15 @@
-# Gitea Actions — act_runner: no setup-php (node24). Toolchain order:
+# Gitea Actions — act_runner: no setup-php (node24).
-# 1) Normalized PATH + existing PHP
+#
-# 2) apt install (only if root or passwordless sudo — interactive sudo would hang)
+# runs-on: ubuntu-latest — use when your runner maps this label to Docker, e.g.
-# 3) Docker or Podman: php:8.2-cli image (runner user in docker group — no host root)
+#   ubuntu-latest:docker://ubuntu:22.04
+# The job then runs *inside* that container (usually as root), so `apt-get install php-*`
+# works without passwordless sudo on the *host*. That avoids the common `ssh` / host-executor
+# setup where the CI user cannot sudo and PHP is missing from PATH.
+#
+# If you only register a custom label like `ssh:host`, either switch this to `runs-on: ssh`
+# or add an ubuntu-latest Docker label to the same runner (see act_runner register --labels).
+#
+# Toolchain order: 1) PATH + existing PHP  2) apt (root/sudo -n)  3) Docker/Podman on host
 #
 # Explicit https://github.com/... action URLs work on all instances.
 
@@ -15,7 +23,7 @@ on:
 
 jobs:
   php:
-    runs-on: ssh
+    runs-on: ubuntu-latest
     steps:
       - uses: https://github.com/actions/checkout@v4
 
@@ -93,7 +101,7 @@ jobs:
             local ctr="$1"
             local img="php:8.2-cli-bookworm"
             log "Running full CI inside $ctr $img (host has no passwordless sudo / no PHP on PATH)."
-            $ctr pull -q "$img" 2>/dev/null || true
+            $ctr pull "$img" || true
             $ctr run --rm \
               -v "$WS:$WS" \
               -w "$WS" \

.github/workflows/ci.yml

@@ -1,4 +1,5 @@
 # GitHub Actions / editor compatibility — keep in sync with `.gitea/workflows/ci.yml`.
+# ubuntu-latest: GitHub-hosted runners; self-hosted runners need a matching label.
 
 name: CI
 
@@ -10,7 +11,7 @@ on:
 
 jobs:
   php:
-    runs-on: ssh
+    runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
 
@@ -88,7 +89,7 @@ jobs:
             local ctr="$1"
             local img="php:8.2-cli-bookworm"
             log "Running full CI inside $ctr $img (host has no passwordless sudo / no PHP on PATH)."
-            $ctr pull -q "$img" 2>/dev/null || true
+            $ctr pull "$img" || true
             $ctr run --rm \
               -v "$WS:$WS" \
               -w "$WS" \

README.md

@@ -198,7 +198,7 @@ composer install
 ./vendor/bin/phpcs --standard=phpcs.xml
 ```
 
-**CI (Gitea Actions):** primary workflow [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml). Gitea checks `.gitea/workflows` before `.github/workflows`, so that file is what runs on Gitea. On Gitea **1.19+**, enable Actions if needed (`[actions] ENABLED=true` before 1.21), register an [act runner](https://docs.gitea.com/usage/actions/act-runner), and ensure a runner accepts `runs-on: ssh` (see [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml); change the label if your runner uses a different one). The job does not use `setup-php` (incompatible with some **act_runner** versions). One step runs **Composer, PHPUnit, PHPStan, and PHPCS** using, in order: **host PHP** (after normalizing `PATH`), **`apt`** only if the user is **root** or has **passwordless sudo** (`sudo -n`), otherwise **`docker`** or **`podman`** with image **`php:8.2-cli-bookworm`** so CI works **without host root** when the runner user can talk to the container engine (`docker info` / `podman info`). If none of that applies, pre-install **`php-cli` 8.1+** on the host or grant **NOPASSWD** sudo / Docker access. [`.github/workflows/ci.yml`](.github/workflows/ci.yml) mirrors the same logic (short `uses:` for checkout). The module’s [`Magesail/composer.json`](Magesail/composer.json) targets Magento **2.4.x** (`magento/framework` **>=103.0 <106**, etc.); install that package inside a Magento project with Composer + `repo.magento.com` credentials.
+**CI (Gitea Actions):** primary workflow [`.gitea/workflows/ci.yml`](.gitea/workflows/ci.yml). It uses **`runs-on: ubuntu-latest`**, which on [act_runner](https://docs.gitea.com/usage/actions/act-runner) should map to a **Docker image** (e.g. `ubuntu-latest:docker://ubuntu:22.04`). To add that label to an already registered runner, see [docs/gitea-act-runner-labels.md](docs/gitea-act-runner-labels.md). The job then runs **inside Ubuntu as root**, so **`apt-get install php-*`** succeeds without passwordless **sudo on the host**—that usually fixes the “no PHP + interactive sudo” situation you get with a **custom host label** like `ssh` / `ssh:host` alone. If you must stay on a bare-metal label only, set `runs-on` to that label and rely on pre-installed PHP, NOPASSWD sudo, or host Docker as described in the workflow comments. The job does not use `setup-php` (incompatible with some act_runner Node runtimes). One step runs **Composer, PHPUnit, PHPStan, and PHPCS** (PATH → apt → optional Docker/Podman fallback on the job environment). [`.github/workflows/ci.yml`](.github/workflows/ci.yml) uses the same `runs-on` (GitHub-hosted **ubuntu-latest** on github.com; align labels if you use self-hosted). The module’s [`Magesail/composer.json`](Magesail/composer.json) targets Magento **2.4.x** (`magento/framework` **>=103.0 <106**, etc.); install that package inside a Magento project with Composer + `repo.magento.com` credentials.
 
 ## License
 

docs/README.md

@@ -21,6 +21,7 @@ PHPUnit, PHPStan (tests + scanned `Model/`), and PHPCS run from the repo root af
 | [php-classes-reference.md](php-classes-reference.md) | PHP classes by layer (quick index) |
 | [scripts.md](scripts.md) | Node scripts, nginx helpers, probes |
 | [troubleshooting.md](troubleshooting.md) | Common failures and fixes |
+| [gitea-act-runner-labels.md](gitea-act-runner-labels.md) | Add `ubuntu-latest` (Docker) labels to an existing Gitea act_runner |
 
 ## Deeper dives (in the module tree)
 

docs/gitea-act-runner-labels.md

@@ -0,0 +1,57 @@
+# Gitea act_runner: add `ubuntu-latest` to an existing runner
+
+You do **not** have to register a second runner. Add the label in the runner **config** and restart; the runner sends updated labels to Gitea on startup.
+
+## 1. Edit the runner `config.yaml`
+
+Find the file you pass to the daemon (e.g. `/etc/act_runner/config.yaml` — check `systemctl cat act_runner` or your Docker `CONFIG_FILE`).
+
+Under **`runner`**, set **`labels`** to a YAML list. Keep your existing label and add **`ubuntu-latest`** with a Docker image (Docker must be installed and the daemon running; the act user needs access to the socket).
+
+Example — **both** host jobs (`ssh`) and Ubuntu container jobs (`ubuntu-latest`):
+
+```yaml
+runner:
+  file: .runner
+  capacity: 1
+  labels:
+    - ssh:host
+    - ubuntu-latest:docker://ubuntu:22.04
+```
+
+- **`ssh:host`** — job steps run on the host (your current behavior).
+- **`ubuntu-latest:docker://ubuntu:22.04`** — jobs with `runs-on: ubuntu-latest` run **inside** that image (root in the container, `apt` works without host sudo).
+
+You can use another image (e.g. `ubuntu:24.04`) or a [Gitea runner image](https://gitea.com/gitea/runner-images) if you prefer.
+
+## 2. Restart the runner
+
+```bash
+sudo systemctl restart act_runner
+# or: docker restart <act_runner_container>
+```
+
+## 3. Confirm in Gitea
+
+**Site administration → Actions → Runners** (or org/repo runners): the runner should list both labels after it reconnects.
+
+## Re-register instead (optional)
+
+If your install only ever stored labels in the register step and not in `config.yaml`, generate a new registration token and run:
+
+```bash
+./act_runner register --no-interactive \
+  --instance 'https://your-gitea.example' \
+  --token '<token>' \
+  --name 'my-runner' \
+  --labels 'ssh:host,ubuntu-latest:docker://ubuntu:22.04'
+```
+
+Prefer editing **`runner.labels` in `config.yaml`** when supported — it avoids rotating tokens and matches how current act_runner [declares labels on startup](https://github.com/go-gitea/gitea/pull/24806).
+
+## Requirements for `docker://` labels
+
+- Docker (or a compatible engine) running on the host.
+- The runner process user in the **`docker`** group, or equivalent access to `/var/run/docker.sock`.
+
+If Docker is not available, keep using a **host-only** label (`*:host`) and pre-install PHP on the host, or use the workflow’s Docker-on-host fallback (see [`.gitea/workflows/ci.yml`](../.gitea/workflows/ci.yml)).