# نشر تطبيق Laravel باستخدام GitHub Actions

> أطلق تطبيق Laravel: جهّز CloudPanel على خادم VPS، وأمّنه عبر Cloudflare، ودع GitHub Actions يختبر وينشر كل تعديل تدفعه تلقائيًا.

*2026-09-17T03:23:45Z*

بناء خط CI/CD لتطبيقك من أجمل ما يمكنك فعله بعد الانتهاء من التطوير، أو حين تريد خادم staging لتجربة مشروعك عليه. في هذا الدليل أشرح المسار الكامل الذي أتبعه لإطلاق تطبيق Laravel: تجهيز خادم VPS جديد باستخدام CloudPanel، ووضعه خلف Cloudflare، واستنساخ المستودع، ثم ربط GitHub Actions بحيث يُختبر كل دفع (push) إلى فرع `master` ويُنشر تلقائيًا.

اتبع الخطوات بالترتيب وستحصل في النهاية على تطبيق ينشر نفسه بنفسه.

## 1. تثبيت CloudPanel

![لوحة تحكم CloudPanel على خادم جديد](https://github.com/tomatophp/docs/raw/master/.gitbook/assets/image%20%281%29.png)

للبدء في العمل على خادم جديد تحتاج عادةً إلى تثبيت الكثير من الحزم، أو استخدام حاوية Docker. أما الطريقة السهلة لبدء نشر تطبيق Laravel بلغة PHP فهي الحصول على VPS من أي مزوّد خدمة مثل AWS EC2 أو Hetzner Cloud. بعد حصولك على الـ VPS، **ويجب أن يعمل بنظام Ubuntu 22.04**، يمكنك متابعة هذا الدرس.

_ملاحظة: كُتب هذا الدليل عام 2023 لنظام Ubuntu 22.04؛ راجع توثيق CloudPanel لمعرفة الإصدارات المدعومة حاليًا._

### ما هو CloudPanel؟

**CloudPanel** لوحة تحكم مجانية وحديثة لإعداد الخوادم وإدارتها، تركّز بشدة على البساطة.

تتيح لك تشغيل تطبيقات **PHP** و**Node.js** و**المواقع الثابتة** و**الوكلاء العكسيين (Reverse Proxies)** و**تطبيقات Python** في وقت قياسي على بنية تقنية عالية الأداء.

وتدعم الإطلاق السريع على:

- [Amazon Web Services](https://www.cloudpanel.io/docs/v2/getting-started/amazon-web-services/installation/ami/)
- [Digital Ocean](https://www.cloudpanel.io/docs/v2/getting-started/digital-ocean/installation/marketplace/)
- [Hetzner Cloud](https://www.cloudpanel.io/docs/v2/getting-started/hetzner-cloud/installation/installer/)
- [Google Compute Engine](https://www.cloudpanel.io/docs/v2/getting-started/google-compute-engine/installation/installer/)
- [Microsoft Azure](https://www.cloudpanel.io/docs/v2/getting-started/microsoft-azure/installation/installer/)
- [Oracle Cloud](https://www.cloudpanel.io/docs/v2/getting-started/oracle-cloud/installation/installer/)
- [Vultr](https://www.cloudpanel.io/docs/v2/getting-started/vultr/installation/marketplace/)
- [مزوّدون آخرون](https://www.cloudpanel.io/docs/v2/getting-started/other/)

![مزوّدو الخدمات السحابية التي يدعمها CloudPanel](https://github.com/tomatophp/docs/raw/master/.gitbook/assets/image%20%282%29.png)

### المزايا

- **مجانية**
- **سهلة الاستخدام**
- **مدعومة من المجتمع**
- **تحميل صفحات فائق السرعة، أسرع حتى 250 مرة**
- **آمنة (شهادات SSL/TLS مجانية)**
- **تكامل مع Cloudflare**
- **أداء عالٍ**
- **جاهزة للعمل خلال دقيقة واحدة**
- **تدعم كل المنصات السحابية الكبرى**
- **تدعم معماريتي x86 وARM**

### التثبيت على الخادم

1. سجّل الدخول إلى خادمك من الطرفية عبر SSH. إن كنت تسجّل الدخول **بكلمة مرور** فالأمر هو:

   ```bash
   ssh root@yourIpAddress
   ```

   وإن كنت تستخدم **مفتاحًا خاصًا** فالأمر هو:

   ```bash
   ssh -i path_to_your_private_key root@yourIpAddress
   ```

2. أنت الآن على حساب root والخادم فارغ. قبل تثبيت اللوحة، حدّث النظام وأضف الحزم التي يحتاجها المثبّت:

   ```bash
   apt update && apt -y upgrade && apt -y install curl wget sudo
   ```

3. الآن ثبّت CloudPanel. يُنزَّل سكربت التثبيت ويُتحقق من بصمته SHA-256، ولا يُنفَّذ إلا بعد ذلك:

   ```bash
   curl -sS https://installer.cloudpanel.io/ce/v2/install.sh -o install.sh; \
   echo "3c30168958264ced81ca9b58dbc55b4d28585d9066b9da085f2b130ae91c50f6 install.sh" | \
   sha256sum -c && sudo bash install.sh
   ```

### الدخول إلى CloudPanel

**الأمان أولًا:** ادخل إلى CloudPanel بأسرع ما يمكن بعد التثبيت وأنشئ المستخدم المدير. هناك نافذة زمنية قصيرة يمكن فيها للبوتات إنشاء هذا المستخدم قبلك. وإن أمكن، افتح المنفذ **8443** لعنوان IP الخاص بك فقط عبر **الجدار الناري**.

يمكنك الآن فتح CloudPanel من المتصفح على العنوان `https://yourIpAddress:8443`.

تجاهل تحذير الشهادة الموقّعة ذاتيًا: اضغط **Advanced** ثم **Proceed** للمتابعة إلى CloudPanel.

![تحذير المتصفح بشأن الشهادة الموقّعة ذاتيًا في CloudPanel](https://www.cloudpanel.io/docs/v2/img/getting-started/ignore-self-signed-certificate.png)

## 2. ربط Cloudflare

![لوحة تحكم Cloudflare](https://github.com/tomatophp/docs/raw/master/.gitbook/assets/image%20%2818%29.png)

أؤمن بأن الأمان والتخزين المؤقت يجعلان أي تطبيق أفضل، لذلك نؤمّن الخادم بوضعه خلف الوكيل العكسي لنظام DNS في Cloudflare والاستفادة من قدراته في التخزين المؤقت.

### إنشاء حساب Cloudflare

إنشاء حساب في Cloudflare سهل كأي موقع آخر: اذهب إلى [صفحة التسجيل](https://dash.cloudflare.com/sign-up) وأنشئ حسابًا جديدًا.

### إضافة نطاقك إلى Cloudflare

![زر إضافة موقع في لوحة Cloudflare](https://github.com/tomatophp/docs/raw/master/.gitbook/assets/image%20%2819%29.png)

1. من لوحة Cloudflare افتح تبويب **Websites** واضغط زر **Add a site** على اليمين.
2. أدخل نطاقك، وستعطيك Cloudflare خوادم الأسماء (nameservers) الخاصة بها.
3. اذهب إلى مزوّد النطاق واستبدل خوادم الأسماء بخوادم Cloudflare.

قد تستغرق هذه العملية حتى 24 ساعة لدى بعض المزوّدين. أنا أستخدم Google Domains ولا تستغرق سوى 10 دقائق، وبعدها يصبح نطاقك فعّالًا على Cloudflare.

_ملاحظة: توقفت خدمة Google Domains منذ ذلك الحين؛ وتغيير خوادم الأسماء يتم بالطريقة نفسها لدى أي مسجّل نطاقات._

### ربط نطاق بـ CloudPanel

1. بعد تفعيل النطاق في Cloudflare افتحه واذهب إلى تبويب **DNS**.
2. أضف سجل `A` جديدًا يوجّه `cp.` إلى عنوان IP الخادم. **تأكد من أن حالة الوكيل (Proxy status) هي DNS only.**
3. في CloudPanel افتح **Admin Area** ثم **Settings**، وغيّر النطاق المخصص للوحة إلى `cp.YOUR_DOMAIN`.

سيولّد CloudPanel شهادة SSL تلقائيًا ويربط النطاق، ومن الآن يمكنك الوصول إلى اللوحة عبر نطاقك الخاص.

### ربط نطاق المشروع

![شاشة إضافة موقع في CloudPanel](https://github.com/tomatophp/docs/raw/master/.gitbook/assets/image%20%2820%29.png)

1. في CloudPanel افتح تبويب **Websites** واضغط **Add Site**، واختر **Create a PHP Site**، واملأ البيانات ثم اضغط **Create**. سيضيف CloudPanel قالب nginx وPHP-FPM لنطاقك.
2. في Cloudflare أضف سجل DNS من نوع `A` لنطاق المشروع يشير إلى خادمك.
3. في Cloudflare أيضًا افتح تبويب **SSL/TLS** وأنشئ شهادة **Origin Server** جديدة. ستحصل على شهادة صالحة لمدة 15 عامًا مجانًا. انسخها.
4. عُد إلى CloudPanel، واختر موقعك الجديد، وافتح تبويب **SSL/TLS** الخاص به، واضغط **Actions** ثم **Import Certificate**، والصق شهادة Cloudflare.

![استيراد شهادة Cloudflare الأصلية في CloudPanel](https://github.com/tomatophp/docs/raw/master/.gitbook/assets/image%20%2821%29.png)

أصبح نطاقك الآن مربوطًا ومؤمّنًا بشهادة SSL. افتحه في المتصفح وتأكد من أنه يعمل.

## 3. استنساخ المستودع

### منح الخادم صلاحية الوصول إلى GitHub

1. سجّل الدخول عبر SSH بمستخدم الموقع الذي أنشأه CloudPanel للمشروع:

   ```bash
   ssh youproject@yourIpAddress
   ```

   أو باستخدام مفتاح خاص:

   ```bash
   ssh -i path_to_your_private_key root@yourIpAddress
   ```

2. بهذا المستخدم، ولّد مفتاح SSH لربط الخادم بمشروعك على GitHub:

   ```bash
   ssh-keygen -t ed25519 -C "your_email@example.com"
   ```

   يمكنك الضغط على Enter عند كل سؤال. عند الانتهاء سيطبع مسار المفتاح العام الذي ينتهي بـ `.pub`.

3. اعرض المفتاح العام وانسخ محتواه:

   ```bash
   cat ~/.ssh/id_ed25519.pub
   ```

   المسار `~/.ssh/id_ed25519.pub` هو المسار الافتراضي لمفتاح ed25519؛ استخدم المسار الذي طبعه `ssh-keygen` إن كان مختلفًا لديك.

4. في مستودعك على GitHub افتح **Settings** ثم **Deploy keys**، واضغط **Add deploy key**، وأعطه اسمًا، والصق المفتاح ثم احفظه.

### استنساخ المشروع

أصبح لخادمك الآن صلاحية الوصول إلى المستودع. انتقل إلى مسار المشروع، ويبدو هكذا:

```bash
cd /home/yourproject/htdocs/yourproject.com
```

ثم استنسخ المستودع داخل المجلد الحالي (لاحظ النقطة `.` في آخر الأمر):

```bash
git clone git@github.com:tomatophp/tomato.git .
```

### إعداد ملف .env

انسخ ملف البيئة النموذجي:

```bash
cp .env.example .env
```

أنشئ قاعدة بيانات جديدة من تبويب **Databases** في CloudPanel، ثم أضف بياناتها إلى `.env`:

```bash
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=tomato-kit
DB_USERNAME=root
DB_PASSWORD=your_password
```

ثم غيّر الرابط الرئيسي للتطبيق:

```bash
APP_URL=https://yourproject.com
APP_HOST=yourproject.com
```

### تثبيت حزم Composer وتنظيف المشروع

ثبّت حزم Composer:

```bash
composer install
```

ثم شغّل أوامر مشروعك، وأهمها:

```bash
php artisan key:generate
php artisan config:cache
php artisan storage:link
php artisan optimize:clear
```

### تثبيت NVM وnpm وYarn

أصبح التطبيق جاهزًا لملفات الواجهة الأمامية، ولهذا تحتاج إلى npm.

1. ثبّت [nvm](https://github.com/nvm-sh/nvm):

   ```bash
   curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.2/install.sh | bash
   ```

2. أعد تحميل بيئة الطرفية الحالية:

   ```bash
   source ~/.bashrc
   ```

3. ثبّت إصدار **Node.js** الذي تحتاجه، مثل **18**:

   ```bash
   nvm install 18
   ```

4. فعّله:

   ```bash
   nvm use 18
   ```

5. تحقق من إصدار Node.js:

   ```bash
   node -v
   ```

6. ثبّت Yarn على مستوى النظام:

   ```bash
   npm -g i yarn
   ```

7. ابنِ ملفات الواجهة:

   ```bash
   yarn && yarn build
   ```

_ملاحظة: كان nvm v0.39.2 وNode.js 18 هما الأحدث عام 2023؛ والإصدارات الأحدث تعمل بالطريقة نفسها._

مشروعك جاهز الآن ويمكنك مشاهدته في المتصفح.

## 4. إنشاء Workflow في GitHub Actions

الخطوة التالية في بناء CI/CD هي ملف workflow بصيغة YAML داخل المستودع. في مشروعك أنشئ مجلد `.github`، وبداخله مجلد `workflows`، وبداخله ملف `ci.yaml`:

```bash
mkdir .github
cd .github
mkdir workflows
cd workflows
touch ci.yaml
```

أضف هذا الـ workflow إلى `ci.yaml`:

```yaml
name: Testing Laravel with MySQL
on:
  pull_request:
    branches:
      - master
  push:
    branches:
      - master

jobs:
  laravel:
    name: Laravel (PHP ${{ matrix.php-versions }})
    runs-on: ubuntu-latest
    env:
      DB_DATABASE: laravel
      DB_USERNAME: root
      DB_PASSWORD: password
      BROADCAST_DRIVER: log
      CACHE_DRIVER: redis
      QUEUE_CONNECTION: redis
      SESSION_DRIVER: redis
    services:
      mysql:
        image: mysql:8.0
        env:
          MYSQL_ALLOW_EMPTY_PASSWORD: false
          MYSQL_ROOT_PASSWORD: password
          MYSQL_DATABASE: laravel
        ports:
          - 3306/tcp
        options: --health-cmd="mysqladmin ping" --health-interval=10s --health-timeout=5s --health-retries=3

      redis:
        image: redis
        ports:
          - 6379/tcp
        options: --health-cmd="redis-cli ping" --health-interval=10s --health-timeout=5s --health-retries=3
    strategy:
      fail-fast: false
      matrix:
        php-versions: ['8.2']
    steps:
      - name: Checkout
        uses: actions/checkout@v4

      - name: Setup PHP
        uses: shivammathur/setup-php@v2
        with:
          php-version: ${{ matrix.php-versions }}
          extensions: sqlite, pdo_sqlite, pcntl, zip, intl, exif, mbstring, dom, fileinfo, mysql
          coverage: xdebug

      - name: Get composer cache directory
        id: composer-cache
        run: echo "dir=$(composer config cache-files-dir)" >> $GITHUB_OUTPUT

      - name: Cache composer dependencies
        uses: actions/cache@v3
        with:
          path: ${{ steps.composer-cache.outputs.dir }}
          # Use composer.json for key, if composer.lock is not committed.
          # key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.json') }}
          key: ${{ runner.os }}-composer-${{ hashFiles('**/composer.lock') }}
          restore-keys: ${{ runner.os }}-composer-


      - name: Install Composer dependencies
        run: composer install --no-progress --prefer-dist --optimize-autoloader

      - name: Prepare Laravel Application
        run: |
          php -r "file_exists('.env') || copy('.env.example', '.env');"
          php artisan key:generate

      - name: Clear Config
        run: php artisan config:clear

      - name: Run Migration
        run: php artisan migrate -v
        env:
          DB_PORT: ${{ job.services.mysql.ports['3306'] }}
          REDIS_PORT: ${{ job.services.redis.ports['6379'] }}

      - name: Test with phpunit
        run: vendor/bin/phpunit --coverage-text
        env:
          DB_PORT: ${{ job.services.mysql.ports['3306'] }}
          REDIS_PORT: ${{ job.services.redis.ports['6379'] }}

      - name: Install Yarn dependencies
        run: yarn

      - name: Compile assets
        run: yarn build

      - name: Deploy to server
        uses: appleboy/ssh-action@master
        with:
          host: ${{ secrets.SSH_HOST }}
          username: ${{ secrets.SSH_USERNAME }}
          port: ${{ secrets.SSH_PORT }}
          password: ${{ secrets.SSH_PASSWORD }}
          script: cd ${{ secrets.SSH_PATH }} && ./.scripts/deploy.sh
```

### ماذا يفعل هذا الـ workflow؟

يعمل الـ workflow مع كل push أو pull request إلى فرع `master`. يشغّل خدمتي MySQL وRedis، ويثبّت PHP واعتماديات Composer، وينفّذ الـ migrations واختبارات PHPUnit، ويبني ملفات الواجهة. ولا تتصل الخطوة الأخيرة بخادمك عبر SSH لتشغيل سكربت النشر إلا بعد نجاح كل ذلك.

### إضافة أسرار الخادم

تقرأ خطوة SSH بيانات الخادم من أسرار GitHub (secrets). في مستودعك على GitHub افتح **Settings** ثم **Secrets and variables** ثم **Actions**، وأضف سرًّا جديدًا لكل مفتاح. على سبيل المثال، يحمل `SSH_HOST` عنوان IP الخادم. ستحتاج إلى كل هذه المفاتيح:

```bash
SSH_HOST: 8.8.8.8
SSH_USERNAME: yourproject
SSH_PORT: 22
SSH_PASSWORD: yourpassword
SSH_PATH: /home/yourproject/htdocs/yourdomain.com
```

ثم تأكد من أن `.env.example` يطابق قاعدة البيانات التي ينشئها الـ workflow، لأنه ينسخه إلى `.env`:

```bash
DB_CONNECTION=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_DATABASE=laravel
DB_USERNAME=root
DB_PASSWORD=password
```

_ملاحظة: كان `actions/cache@v3` هو الإصدار الحالي وقت كتابة المقال؛ وقد أصدرت GitHub إصدارات رئيسية أحدث منذ ذلك الحين._

## 5. كتابة سكربت النشر

سكربت النشر هو ما يُنفَّذ على الخادم في كل مرة تدفع فيها تعديلاتك، لذا يجب أن يحتوي على كل أمر تريد تشغيله مع كل عملية نشر.

أنشئ مجلد `.scripts` وبداخله ملف `deploy.sh`، وامنح الملف الصلاحية 755 ليكون قابلًا للتنفيذ:

```bash
mkdir .scripts
cd .scripts
touch deploy.sh
chmod 755 deploy.sh
```

أضف هذا السكربت إلى الملف وعدّله كما تشاء:

```bash
#!/bin/bash
set -e

echo "Deployment started ..."

# Enter maintenance mode or return true
# if already is in maintenance mode
(php artisan down) || true

# Pull the latest version of the app
git reset --hard
git pull origin master

# Install composer dependencies
composer install --no-dev --no-interaction --prefer-dist --optimize-autoloader

# Clear the old cache
php artisan clear-compiled

# Recreate cache
php artisan optimize

# Compile npm assets
yarn
yarn build

# Run database migrations
php artisan migrate --force

# Exit maintenance mode
php artisan up

echo "Deployment finished!"
```

يضع السكربت التطبيق في وضع الصيانة، ويسحب أحدث نسخة من الكود، ويثبّت اعتماديات الإنتاج، ويعيد بناء الذاكرة المؤقتة وملفات الواجهة، وينفّذ الـ migrations، ثم يعيد التطبيق للعمل. وبفضل `set -e` يتوقف عند أول أمر يفشل.

## الخلاصة

ادفع كل هذه التعديلات إلى مستودعك على GitHub. افتح تبويب **Actions** وسترى الـ workflow يعمل، وبمجرد انتهائه تصبح التحديثات منشورة على خادمك.

من الآن فصاعدًا، يُختبر كل push إلى `master` أولًا ولا يُنشر إلا إذا نجحت الاختبارات، بينما يدير CloudPanel الخادم وتحميه Cloudflare وتخزّن محتواه مؤقتًا.

---

Source: https://fadymondy.com/ar/blog/deploy-laravel-app-using-github-actions
