دیپلوی وردپرس با Git و GitHub Actions روی هاست ایرانی (راهنمای کامل)

دیپلوی وردپرس با Git یعنی هر تغییر کد با یک git push به صورت خودکار، تست‌شده و قابل بازگشت روی سرور می‌نشیند؛ بدون FTP، بدون فایل جامانده و بدون «روی سیستم من کار می‌کرد». این راهنما یک پایپ‌لاین کامل با GitHub Actions می‌سازد که قالب و افزونه‌های اختصاصی را بیلد می‌کند، با rsync منتقل می‌کند، با WP-CLI کش را خالی می‌کند و سلامت سایت را می‌سنجد. چون رانرهای GitHub خارج از ایران‌اند، سه استراتژی مختلف برای VPS خارجی، VPS ایرانی و هاست اشتراکی ایرانی ارائه شده است.

آنچه در این آموزش یاد می‌گیرید

• ساختار درست ریپوی وردپرس و فایل .gitignore کامل

• آماده‌سازی سرور: کاربر محدود deploy، کلید SSH و پوشه‌بندی اتمیک

• workflow کامل GitHub Actions با بیلد قالب و بلاک، Composer، rsync، WP-CLI و سلامت‌سنجی

• استقرار اتمیک با پوشه‌ی releases و بازگشت یک‌ثانیه‌ای

• سه استراتژی برای هاست ایرانی: رانر ابری، رانر self-hosted و استقرار pull با کران‌جاب

• محیط staging، تأیید انسانی قبل از production و همگام‌سازی دیتابیس

• امنیت، خطاهای رایج و چیزهایی که هرگز نباید وارد گیت شوند

چرا FTP کافی نیست

با FTP هیچ‌کس نمی‌داند چه فایلی کی و توسط چه کسی تغییر کرده. یک آپلود ناقص سایت را می‌شکند و برگشت یعنی پیدا کردن نسخه‌ی قبلی روی لپ‌تاپ کسی. گیت این سه مشکل را یک‌جا حل می‌کند: تاریخچه‌ی کامل، بازبینی کد قبل از انتشار و بازگشت به هر نقطه. GitHub Actions این را یک قدم جلوتر می‌برد: بیلد و تست روی ماشین تمیز انجام می‌شود، نه روی سرور زنده، و هیچ فایلی دستی جابه‌جا نمی‌شود.

ساختار ریپو: چه چیزی در گیت باشد

فقط کد اختصاصی شما در گیت است. هسته و افزونه‌های مخزن در دیپلوی نصب می‌شوند و داده‌ها جداگانه مدیریت می‌شوند.

اشتباه رایج این است که کل پوشه‌ی وردپرس را commit کنند. نتیجه ریپویی چند صد مگابایتی با هزاران فایل هسته است که هر به‌روزرسانی وردپرس آن را به‌هم می‌ریزد. قاعده‌ی ساده: هر چیزی که خودتان ننوشته‌اید یا داده‌ی کاربر است، بیرون از گیت. این فایل .gitignore را در ریشه‌ی پروژه بگذارید و نام قالب و افزونه‌هایتان را جایگزین کنید:

# هسته‌ی وردپرس (با wp-cli یا composer نصب می‌شود)
/wp-admin/
/wp-includes/
/wp-*.php
/index.php
/license.txt
/readme.html
/xmlrpc.php

# رمزها و تنظیمات محیط
wp-config.php
.env
.env.*

# محتوای کاربر و فایل‌های موقت
/wp-content/uploads/
/wp-content/cache/
/wp-content/upgrade/
/wp-content/backup*/
/wp-content/debug.log

# افزونه‌ها و قالب‌های مخزن وردپرس (در deploy نصب می‌شوند)
/wp-content/plugins/*
!/wp-content/plugins/wpkala-*/
/wp-content/themes/*
!/wp-content/themes/wpkala-theme/

# خروجی بیلد و وابستگی‌ها
node_modules/
vendor/
/wp-content/themes/wpkala-theme/build/
/wp-content/plugins/wpkala-blocks/build/

# فایل‌های سیستم و ویرایشگر
.DS_Store
Thumbs.db
.idea/
.vscode/

افزونه‌های مخزن وردپرس را یا با Composer و بسته‌ی wpackagist مدیریت کنید یا در مرحله‌ی دیپلوی با wp plugin install نصب کنید. هر دو راه نسخه‌ی دقیق افزونه را در کد ثبت می‌کنند و سرور را از لوکال و staging یکسان نگه می‌دارند. اگر به سراغ Composer می‌روید، ساختار Bedrock از Roots همین کارها را با استاندارد آماده انجام می‌دهد، اما برای هاست اشتراکی ساختار ساده‌ی این مقاله کافی است.

آماده‌سازی سرور

ساختار پوشه‌ها برای استقرار اتمیک. وب‌سرور همیشه به current اشاره می‌کند و هر دیپلوی فقط این لینک را عوض می‌کند.

ایده‌ی استقرار اتمیک این است که هیچ‌وقت روی فایل‌های سایت زنده نمی‌نویسیم. هر دیپلوی در پوشه‌ی جدیدی داخل releases ساخته می‌شود، فایل‌های مشترک (wp-config، آپلودها و هسته) از shared به آن لینک می‌شوند و در پایان symlink به نام current به نسخه‌ی جدید می‌چرخد. وب‌سرور در تمام مدت یا نسخه‌ی قبلی را می‌بیند یا نسخه‌ی کامل جدید را؛ هرگز حالت نیمه‌کاره وجود ندارد. بازگشت هم فقط برگرداندن همین لینک است.

# روی سرور، یک بار با کاربر دارای sudo
sudo adduser --disabled-password --gecos "" deploy
sudo mkdir -p /var/www/site/{releases,shared/uploads}
sudo chown -R deploy:www-data /var/www/site
sudo chmod -R 2775 /var/www/site

# کلید عمومی دیپلوی را برای کاربر deploy ثبت کنید
sudo -u deploy mkdir -p /home/deploy/.ssh
sudo -u deploy tee -a /home/deploy/.ssh/authorized_keys < deploy_key.pub
sudo chmod 700 /home/deploy/.ssh && sudo chmod 600 /home/deploy/.ssh/authorized_keys

# هسته‌ی وردپرس و wp-config در shared می‌مانند
cd /var/www/site/shared
sudo -u deploy wp core download --locale=fa_IR --skip-content
sudo -u deploy wp config create --dbname=site --dbuser=site --dbpass='رمز' --dbhost=localhost

ریشه‌ی وب‌سرور را روی /var/www/site/current تنظیم کنید. در nginx یعنی root /var/www/site/current; و در آپاچی DocumentRoot /var/www/site/current. گزینه‌ی --skip-content هسته را بدون قالب‌ها و افزونه‌های پیش‌فرض دانلود می‌کند، چون آن‌ها از گیت می‌آیند.

کلید دیپلوی و Secrets

کلید خصوصی فقط در Secrets ریپو، کلید عمومی فقط روی سرور. کاربر deploy به چیزی جز پوشه‌ی سایت دسترسی ندارد.

# روی لپ‌تاپ خودتان: کلید فقط برای دیپلوی، بدون passphrase
ssh-keygen -t ed25519 -C "github-deploy" -f deploy_key -N ""

# محتوای deploy_key (خصوصی)  →  GitHub › Settings › Secrets › SSH_PRIVATE_KEY
# محتوای deploy_key.pub (عمومی) →  روی سرور در authorized_keys کاربر deploy
cat deploy_key
cat deploy_key.pub

در GitHub به Settings › Environments بروید، محیط production را بسازید و این Secrets را در آن تعریف کنید: SSH_PRIVATE_KEY، DEPLOY_HOST، DEPLOY_USER (deploy)، DEPLOY_PORT (معمولاً ۲۲) و DEPLOY_PATH (/var/www/site). یک Variable به نام SITE_URL هم برای سلامت‌سنجی بگذارید. تعریف در سطح Environment به جای ریپو اجازه می‌دهد بعداً برای staging مقادیر جداگانه داشته باشید و برای production تأییدکننده تعیین کنید.

workflow کامل GitHub Actions

پنج مرحله‌ی پایپ‌لاین. شکست در هر مرحله اجرای مراحل بعد را متوقف می‌کند و سایت دست‌نخورده می‌ماند.

این فایل را در مسیر .github/workflows/deploy.yml بگذارید. با هر push به شاخه‌ی main اجرا می‌شود و با workflow_dispatch می‌توانید دستی هم اجرایش کنید:

# .github/workflows/deploy.yml
name: Deploy to production

on:
  push:
    branches: [main]
  workflow_dispatch:

concurrency:
  group: production
  cancel-in-progress: false

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production
    timeout-minutes: 15

    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Setup Node
        uses: actions/setup-node@v4
        with:
          node-version: 22
          cache: npm
          cache-dependency-path: wp-content/themes/wpkala-theme/package-lock.json

      - name: Build theme assets
        working-directory: wp-content/themes/wpkala-theme
        run: |
          npm ci
          npm run build

      - name: Build blocks plugin
        working-directory: wp-content/plugins/wpkala-blocks
        run: |
          npm ci
          npm run build

      - name: Setup PHP and Composer
        uses: shivammathur/setup-php@v2
        with:
          php-version: '8.3'
          tools: composer

      - name: Install PHP dependencies (production only)
        run: composer install --no-dev --optimize-autoloader --no-interaction

      - name: Start SSH agent
        uses: webfactory/ssh-agent@v0.9.1
        with:
          ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}

      - name: Trust server host key
        run: ssh-keyscan -p ${{ secrets.DEPLOY_PORT }} -H ${{ secrets.DEPLOY_HOST }} >> ~/.ssh/known_hosts

      - name: Upload release
        env:
          HOST: ${{ secrets.DEPLOY_HOST }}
          USER: ${{ secrets.DEPLOY_USER }}
          PORT: ${{ secrets.DEPLOY_PORT }}
          BASE: ${{ secrets.DEPLOY_PATH }}
        run: |
          RELEASE=$(date +%Y%m%d-%H%M%S)-${GITHUB_SHA::7}
          echo "RELEASE=$RELEASE" >> "$GITHUB_ENV"
          rsync -az --delete \
            --exclude='.git' --exclude='.github' --exclude='node_modules' \
            --exclude='**/src' --exclude='*.map' \
            -e "ssh -p $PORT" \
            ./ "$USER@$HOST:$BASE/releases/$RELEASE/"

      - name: Activate release and run WP-CLI
        env:
          HOST: ${{ secrets.DEPLOY_HOST }}
          USER: ${{ secrets.DEPLOY_USER }}
          PORT: ${{ secrets.DEPLOY_PORT }}
          BASE: ${{ secrets.DEPLOY_PATH }}
        run: |
          ssh -p "$PORT" "$USER@$HOST" "bash -s" <<EOF
            set -euo pipefail
            cd "$BASE"
            R="releases/$RELEASE"
            # فایل‌های مشترک به نسخه‌ی جدید لینک می‌شوند
            ln -sfn "$BASE/shared/wp-config.php" "$R/wp-config.php"
            ln -sfn "$BASE/shared/uploads" "$R/wp-content/uploads"
            for f in wp-admin wp-includes index.php wp-*.php; do ln -sfn "$BASE/shared/\$f" "$R/\$f"; done
            # تعویض اتمیک
            ln -sfn "$BASE/$R" "$BASE/current"
            cd "$BASE/current"
            wp core update-db --quiet
            wp cache flush --quiet
            wp rewrite flush --hard --quiet
            # فقط ۵ نسخه‌ی آخر را نگه دار
            cd "$BASE/releases" && ls -1dt */ | tail -n +6 | xargs -r rm -rf
          EOF

      - name: Health check
        run: |
          for i in 1 2 3; do
            curl -fsS -o /dev/null "https://${{ vars.SITE_URL }}/" && exit 0
            sleep 5
          done
          echo "Site did not respond with 200" && exit 1

چند تصمیم در این workflow عمدی است:

• concurrency نمی‌گذارد دو دیپلوی هم‌زمان اجرا شوند. اگر دو کامیت پشت سر هم push شود، دومی صبر می‌کند.

• بیلد روی رانر انجام می‌شود نه روی سرور. سرور به Node نیاز ندارد و پوشه‌های src و node_modules هرگز منتقل نمی‌شوند.

• rsync با --delete فایل‌های حذف‌شده از ریپو را از نسخه‌ی جدید هم حذف می‌کند. چون هر نسخه پوشه‌ی جداگانه دارد، این پرچم خطری برای آپلودها ندارد.

• WP-CLI بعد از تعویض اجرا می‌شود: به‌روزرسانی ساختار دیتابیس، خالی کردن کش و بازسازی پیوندها. دستورهای بیشتر را در مقاله‌ی WP-CLI وردپرس کالا ببینید.

• سلامت‌سنجی سه بار کد ۲۰۰ را می‌خواهد. اگر نگرفت workflow قرمز می‌شود و شما بلافاصله می‌فهمید، نه کاربر.

• فقط پنج نسخه‌ی آخر نگه داشته می‌شود تا دیسک پر نشود؛ عدد را به دلخواه تغییر دهید.

تنظیمات محیط در wp-config

// wp-config.php (در shared): مقادیر از متغیر محیطی یا فایل .env خوانده می‌شوند
define( 'WP_ENVIRONMENT_TYPE', getenv( 'WP_ENV' ) ?: 'production' );
define( 'DISALLOW_FILE_MODS', WP_ENVIRONMENT_TYPE === 'production' ); // نصب افزونه فقط از طریق گیت
define( 'DISABLE_WP_CRON', true );                                     // کران واقعی با WP-CLI
define( 'WP_DEBUG', WP_ENVIRONMENT_TYPE !== 'production' );
define( 'AUTOMATIC_UPDATER_DISABLED', true );                          // به‌روزرسانی‌ها هم از مسیر دیپلوی

ثابت DISALLOW_FILE_MODS مهم‌ترین خط است: در production هیچ‌کس نمی‌تواند از پیشخوان افزونه نصب یا فایل ویرایش کند. تنها راه تغییر کد همان گیت است و این یعنی سرور همیشه با ریپو یکی است.

سه استراتژی برای هاست‌های ایرانی

انتخاب استراتژی به این بستگی دارد که فایروال هاست SSH ورودی از IP خارجی را می‌پذیرد یا نه.

رانرهای رایگان GitHub روی سرورهای مایکروسافت خارج از ایران اجرا می‌شوند. workflow بالا از همان‌جا به سرور شما SSH می‌زند. بسیاری از هاست‌های ایرانی SSH ورودی از IP خارجی را می‌بندند یا فقط با درخواست باز می‌کنند. اگر در لاگ workflow پیام Connection timed out دیدید، همین است. دو راه‌حل دارید:

استراتژی ۲: رانر self-hosted روی سرور ایرانی

رانر یک سرویس کوچک است که روی سرور خودتان نصب می‌شود و خودش به GitHub وصل می‌شود تا job بگیرد. ارتباط همیشه از سرور به بیرون است، پس هیچ پورتی باز نمی‌شود و فایروال مشکلی ندارد. بیلد و کپی فایل‌ها هم روی همان سرور انجام می‌شود و دیگر rsync از راه دور لازم نیست:

# روی VPS ایرانی با کاربر deploy (دستور دقیق را GitHub در Settings › Actions › Runners می‌دهد)
mkdir -p ~/actions-runner && cd ~/actions-runner
curl -o actions-runner-linux-x64.tar.gz -L https://github.com/actions/runner/releases/latest/download/actions-runner-linux-x64.tar.gz
tar xzf actions-runner-linux-x64.tar.gz
./config.sh --url https://github.com/USER/REPO --token TOKEN --labels iran-prod --unattended
sudo ./svc.sh install deploy && sudo ./svc.sh start

jobs:
  deploy:
    runs-on: [self-hosted, iran-prod]
    environment: production
    steps:
      - uses: actions/checkout@v7
      - name: Build
        run: |
          cd wp-content/themes/wpkala-theme && npm ci && npm run build
      - name: Release (local copy, no SSH needed)
        run: |
          RELEASE=$(date +%Y%m%d-%H%M%S)
          rsync -az --delete --exclude='.git' ./ /var/www/site/releases/$RELEASE/
          /var/www/site/deploy/activate.sh "$RELEASE"

رانر را با کاربر deploy نصب کنید نه root، و برچسب (label) اختصاصی بدهید تا job های دیگر روی آن اجرا نشوند. برای ریپوهای عمومی رانر self-hosted نگذارید؛ هر کسی با یک Pull Request می‌تواند روی سرور شما کد اجرا کند. نیاز به Node روی سرور دارید که روی VPS ساده است.

استراتژی ۳: استقرار pull برای هاست اشتراکی

هاست اشتراکی نه Node دارد نه اجازه‌ی نصب سرویس. اما اگر SSH و git داشته باشد (بیشتر هاست‌های ایرانی دارند) سرور می‌تواند خودش هر چند دقیقه ریپو را بررسی کند و در صورت تغییر، نسخه‌ی جدید را بگیرد. در این حالت خروجی بیلد (پوشه‌ی build) را در ریپو commit می‌کنید یا در یک شاخه‌ی جداگانه‌ی deploy با Actions می‌سازید و push می‌کنید:

#!/usr/bin/env bash
# /var/www/site/deploy/pull.sh : استقرار pull برای هاست اشتراکی (اجرا با کران‌جاب)
set -euo pipefail
cd /home/USER/public_html/wp-content/themes/wpkala-theme

# فقط اگر کامیت جدیدی روی main هست
git fetch --quiet origin main
if [ "$(git rev-parse HEAD)" = "$(git rev-parse origin/main)" ]; then
  exit 0
fi

git reset --hard origin/main
# بیلد از قبل در ریپو کامیت شده (پوشه‌ی build) چون هاست اشتراکی Node ندارد
wp cache flush --path=/home/USER/public_html --quiet
echo "$(date) deployed $(git rev-parse --short HEAD)" >> /home/USER/deploy.log

# crontab -e : هر پنج دقیقه بررسی کن
*/5 * * * * /home/USER/deploy/pull.sh >> /home/USER/deploy-cron.log 2>&1

برای اینکه هاست بتواند ریپوی خصوصی را بخواند، یک Deploy Key فقط‌خواندنی در Settings › Deploy keys ریپو بسازید و کلید خصوصی‌اش را در ~/.ssh هاست بگذارید. این روش اتمیک نیست و بیلد را روی رانر انجام نمی‌دهد، اما از FTP هزار بار بهتر است و برای سایت‌های کوچک کاملاً کافی است.

محیط staging و تأیید قبل از production

یک شاخه‌ی staging بسازید که به زیردامنه‌ی staging دیپلوی شود. همان workflow با یک خط تغییر هر دو محیط را پوشش می‌دهد و Secrets هر محیط جداگانه خوانده می‌شود:

on:
  push:
    branches: [main, staging]

jobs:
  deploy:
    runs-on: ubuntu-latest
    # شاخه‌ی staging به محیط staging و main به production
    environment: ${{ github.ref_name == 'main' && 'production' || 'staging' }}
    steps:
      - uses: actions/checkout@v7
      # ... همان مراحل؛ Secrets هر محیط جداگانه تعریف می‌شود

در Settings › Environments › production گزینه‌ی Required reviewers را فعال کنید. از این به بعد هر push به main منتظر می‌ماند تا یکی از تأییدکننده‌ها در صفحه‌ی Actions روی Approve بزند. برای تیم‌های دو سه نفره همین یک قدم بیشتر حوادث را حذف می‌کند.

همگام‌سازی دیتابیس و آپلودها

جهت داده همیشه از production به staging است، هرگز برعکس. دیتابیس زنده را روی staging کپی کنید تا با داده‌ی واقعی تست کنید، و آپلودها را با rsync بیاورید یا در staging به آدرس production وصل کنید:

# کپی دیتابیس production روی staging (هرگز برعکس)
ssh deploy@prod "cd /var/www/site/current && wp db export - | gzip" | gunzip | \
  ssh deploy@staging "cd /var/www/staging/current && wp db import -"
ssh deploy@staging "cd /var/www/staging/current && \
  wp search-replace 'https://site.ir' 'https://staging.site.ir' --all-tables --skip-columns=guid && \
  wp option update blog_public 0"

خط آخر staging را از ایندکس گوگل پنهان می‌کند. اگر بخواهید staging را با رمز هم ببندید، یک Basic Auth در nginx کافی است.

امنیت در پایپ‌لاین

• کلید دیپلوی فقط برای همین کار ساخته می‌شود و با کاربر deploy که sudo ندارد وارد می‌شود. کلید شخصی خودتان هرگز در Secrets نمی‌رود.

• اکشن‌های شخص ثالث را به نسخه‌ی مشخص (یا SHA کامیت) پین کنید. در این مقاله فقط اکشن‌های رسمی GitHub و دو اکشن پرکاربرد با نسخه‌ی ثابت استفاده شده‌اند.

• Secrets در لاگ نمایش داده نمی‌شوند اما اگر آن‌ها را با echo چاپ کنید، GitHub فقط بخشی را ماسک می‌کند. هیچ‌وقت چاپشان نکنید.

• wp-config و .env خارج از گیت و خارج از پوشه‌ی هر نسخه در shared می‌مانند؛ هیچ دیپلویی آن‌ها را بازنویسی نمی‌کند.

• با DISALLOW_FILE_MODS پیشخوان را از ویرایش فایل محروم کنید تا کد سرور همیشه برابر ریپو باشد و هک از طریق ویرایشگر قالب غیرممکن شود.

• برای ریپوی عمومی هرگز رانر self-hosted نگذارید و workflow را فقط روی push به main (نه pull_request) اجرا کنید.

خطاهای رایج و راه‌حل