The aaPanel PHP path bug that broke GitLab CI (and the one-line fix)

Short answer: aaPanel installs PHP at /www/server/php/84/bin/php, but GitLab shell runners login as gitlab-runner with a minimal PATH—so CI failed until scripts/ci-env.sh prepended that directory.

Symptom

$ php artisan test
bash: php: command not found

Local Sail worked; production runner did not.

Fix

# scripts/ci-env.sh
export PATH="/www/server/php/84/bin:$PATH"

Source in .gitlab-ci.yml:

before_script:
  - source scripts/ci-env.sh

Also in deploy_production.sh for consistent artisan calls.

Lessons

• Never assume panel PHP is global
• Pin PHP minor in path when aaPanel upgrades (84 → 85)
• Document in repo—not wiki

Related pipeline docs

• GitLab + aaPanel deploys
• Pest before deploy

FAQ

Use update-alternatives instead?

Could—aaPanel mutates alternatives on upgrade; explicit path is predictable.

Composer path too?

composer often in /usr/local/bin—verify with which composer as runner user.

Docker executor?

Would isolate PHP version—future option if shell runner pain grows.

Maintenance note (Sep 2026)

Re-checked this runbook against the current aviwebsquad.in production host after the VPS move to Hostinger (72.61.235.205). Steps above still match the live deploy path under /www/wwwroot/aviwebsquad.in.