هر بار که کد را پوش می‌کنی، آیا دستی تست‌ها را اجرا می‌کنی، پروژه را بیلد می‌گیری و فایل‌ها را با FTP روی سرور آپلود می‌کنی؟ این چرخه خسته‌کننده نه‌تنها وقت تو را می‌گیرد، بلکه یک اشتباه کوچک می‌تواند سایت را پایین بیاورد. خبر خوب این است که می‌توانی همه این کارها را به گیت‌هاب بسپاری تا خودش، خودکار و بدون خطا انجام دهد. در این راهنما یاد می‌گیری چطور با GitHub Actions یک پایپ‌لاین CI/CD کامل برای پروژه‌های پایتون و جاوااسکریپت بسازی؛ از اجرای خودکار تست‌ها تا دیپلوی روی سرور و Vercel.

GitHub Actions چیست و چرا برای هر برنامه‌نویس ضروری است؟

GitHub Actions سرویس اتوماسیون داخلی گیت‌هاب است که با هر رویداد مثل push یا pull request، یک ورک‌فلو تعریف‌شده توسط تو را روی یک ماشین مجازی اجرا می‌کند تا تست، بیلد، لینت و دیپلوی را خودکار کند. با یک فایل YAML ساده در مسیر .github/workflows می‌توانی پایپ‌لاین CI/CD حرفه‌ای بسازی، وابستگی‌ها را کش کنی، روی چند نسخه پایتون/نود تست بگیری و با Secrets به‌صورت امن دیپلوی کنی. در ادامه قدم‌به‌قدم همین فایل را می‌سازیم.

GitHub Actions چیست و چطور کار می‌کند؟

اگر تا امروز فکر می‌کردی CI/CD یک ابزار گران و پیچیده فقط برای شرکت‌های بزرگ است، GitHub Actions این تصور را کاملاً عوض کرده است. این سرویس از سال ۲۰۱۹ به‌صورت رایگان برای ریپازیتوری‌های عمومی و با سهم رایگان سخاوتمندانه برای ریپازیتوری‌های خصوصی ارائه می‌شود و مستقیماً داخل گیت‌هاب زندگی می‌کند. یعنی نیازی به نصب سرور جداگانه مثل Jenkins نداری.

ایده اصلی ساده است: تو می‌گویی «هر وقت این اتفاق افتاد، این کارها را انجام بده» و گیت‌هاب بدون دخالت تو انجامش می‌دهد. مثلاً «هر وقت روی شاخه main پوش شد، تست‌های پایتون را اجرا کن و اگر سبز بود، به سرور دیپلوی کن».

مفاهیم کلیدی: Workflow، Job، Step و Runner

برای کار با Actions باید چهار مفهوم را بشناسی:

Workflow: خودِ پایپ‌لاین. یک فایل YAML در پوشه .github/workflows/main.yml. هر ریپو می‌تواند چند Workflow داشته باشد.
Event (Trigger): محرک اجرا؛ مثل push، pull_request، schedule (زمان‌بندی کرون) یا حتی workflow_dispatch برای اجرای دستی.
Job: یک دسته از کارها که روی یک Runner اجرا می‌شود. هر Job به‌صورت پیش‌فرض موازی اجرا می‌شود، مگر اینکه وابستگی تعریف کنی.
Step: یک دستور منفرد داخل Job؛ مثلاً checkout کردن کد یا اجرای pip install. Stepها به ترتیب اجرا می‌شوند.
Runner: ماشین مجازی که Job روی آن اجرا می‌شود؛ ubuntu-latest، windows-latest یا macos-latest. می‌توانی Runner شخصی (self-hosted) هم داشته باشی.
Action: یک اپلیکیشن آماده قابل استفاده مجدد. مثلاً actions/checkout@v4 برای کلون کردن کد یا actions/setup-python@v5 برای نصب پایتون.

وقتی این‌ها را کنار هم بگذاری، یک Workflow مثل یک دستور آشپزی می‌شود: مواد اولیه (Trigger)، ظروف (Runner)، مراحل پخت (Steps) و نتیجه نهایی (Artifact یا Deploy).

تفاوت GitHub Actions با Jenkins و GitLab CI

خیلی‌ها می‌پرسند چرا Actions و نه Jenkins یا GitLab CI؟ جواب به نیاز تو برمی‌گردد، اما این مقایسه به تصمیم کمک می‌کند:

ویژگی	GitHub Actions	GitLab CI	Jenkins
محل اجرا	داخل گیت‌هاب، بدون سرور اضافی	داخل گیت‌لب، نیاز به Runner	سرور شخصی تو، خودت نگهداری می‌کنی
هزینه شروع	رایگان برای عمومی؛ ۲۰۰۰ دقیقه رایگان ماهانه برای خصوصی	رایگان محدود، نیاز به کردیت	رایگان اما هزینه سرور و نگهداری
پیکربندی	YAML ساده در .github/workflows	.gitlab-ci.yml	Groovy/Jenkinsfile پیچیده‌تر
اکوسیستم Action	بیش از ۲۰ هزار Action آماده در Marketplace	تمپلیت‌ها و کامپوننت‌ها	پلاگین‌های فراوان اما قدیمی‌تر
مناسب برای	تیم‌های کوچک تا متوسط، پروژه‌های اوپن‌سورس	تیم‌هایی که روی گیت‌لب هستند	سازمان‌های بزرگ با نیاز سفارشی‌سازی عمیق
سرعت راه‌اندازی	کمتر از ۵ دقیقه	کمتر از ۱۰ دقیقه	نیم ساعت تا چند ساعت

برای یک برنامه‌نویس مستقل یا تیم استارتاپی، Actions سریع‌ترین راه برای رسیدن به CI/CD واقعی است؛ بدون اینکه یک DevOps تمام‌وقت استخدام کنی.

ساخت اولین Workflow؛ اجرای تست‌ها در هر Push

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

قدم اول: ساخت فایل YAML در مسیر .github/workflows

در ریشه پروژه، پوشه .github/workflows را بساز و یک فایل به نام ci.yml داخل آن قرار بده. نام فایل مهم نیست، اما پسوند باید .yml یا .yaml باشد.

name: CI Pipeline
on:
  push:
    branches: [main, develop]
  pull_request:
    branches: [main]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Setup Python
        uses: actions/setup-python@v5
        with:
          python-version: "3.11"
      - name: Install dependencies
        run: pip install -r requirements.txt
      - name: Run tests
        run: pytest -q

همین چهار Step کار را راه می‌اندازد. وقتی این فایل را کامیت و پوش کنی، در تب Actions گیت‌هاب، اجرای آن را به‌صورت زنده می‌بینی؛ تیک سبز یعنی موفقیت، ضربدر قرمز یعنی تست فِیل شده.

قدم دوم: تعریف Trigger هوشمند و جلوگیری از اجرای بیهوده

اجرای پایپ‌لاین برای هر تغییر کوچک ممکن است کردیت تو را هدر دهد. می‌توانی Trigger را دقیق کنی:

اجرای فقط روی تغییر فایل‌های خاص: با paths بگو فقط وقتی پوشه src/** یا requirements.txt تغییر کرد اجرا شود.
نادیده گرفتن تغییرات مستندات: با paths-ignore: ['**.md'] از اجرای بیهوده برای README جلوگیری کن.
زمان‌بندی: با schedule: - cron: '0 2 * * *' هر شب ساعت ۲ بامداد تست‌ها را اجرا کن تا از سالم بودن وابستگی‌ها مطمئن شوی.

on:
  push:
    paths:
      - 'src/**'
      - 'requirements.txt'
    paths-ignore:
      - '**.md'
  schedule:
    - cron: '0 2 * * 1'  # هر دوشنبه ساعت 2
  workflow_dispatch:  # اجازه اجرای دستی از رابط گیت‌هاب

قدم سوم: Cache کردن وابستگی‌ها برای سرعت ۳ برابری

نصب دوباره pip یا npm در هر اجرا ۱ تا ۳ دقیقه وقت می‌گیرد. با کش کردن، این زمان به ۲۰ ثانیه می‌رسد:

- name: Cache pip
  uses: actions/cache@v4
  with:
    path: ~/.cache/pip
    key: ${{ runner.os }}-pip-${{ hashFiles('requirements.txt') }}
    restore-keys: |
      ${{ runner.os }}-pip-

برای پروژه‌های پایتون مدرن که از uv برای مدیریت پکیج‌ها استفاده می‌کنند، همین الگو با astral-sh/setup-uv حتی سریع‌تر می‌شود؛ چون uv خودش کش داخلی دارد و ۱۰ تا ۱۰۰ برابر سریع‌تر از pip نصب می‌کند. اگر هنوز uv را امتحان نکرده‌ای، راهنمای کامل uv نقطه شروع عالی است.

پایپ‌لاین حرفه‌ای برای پروژه پایتون با uv و Ruff و Pytest

حالا یک پایپ‌لاین واقعی و تمیز بسازیم که سه کار را هم‌زمان انجام دهد: فرمت و لینت با Ruff، تست با Pytest و چک تایپ با mypy.

name: Python CI
on: [push, pull_request]
jobs:
  quality:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: astral-sh/setup-uv@v3
        with:
          enable-cache: true
      - name: Install deps
        run: uv sync --all-extras --dev
      - name: Lint with Ruff
        run: uv run ruff check .
      - name: Format check
        run: uv run ruff format --check .
      - name: Type check
        run: uv run mypy src
      - name: Tests
        run: uv run pytest --cov=src --cov-report=term-missing
      - name: Upload coverage
        uses: codecov/codecov-action@v4
        with:
          token: ${{ secrets.CODECOV_TOKEN }}

چرا این ترکیب محبوب است؟ Ruff همه‌کاره و فوق‌سریع است و جایگزین flake8 و isort و black شده، Pytest استاندارد تست در پایتون است و uv نصب را برق‌آسا می‌کند. اگر پروژه‌ات اسکریپینگ یا جمع‌آوری داده دارد، می‌توانی بعد از تست، یک Job دیگر اضافه کنی که اسکریپت وب اسکرپینگ را روی داده تستی اجرا کند تا مطمئن شوی Parser نشکسته است.

نکته طلایی: خروجی هر Job را به‌عنوان Artifact ذخیره کن تا بعداً دانلود شود:

- name: Upload test results
  if: always()
  uses: actions/upload-artifact@v4
  with:
    name: pytest-results
    path: junit.xml

پایپ‌لاین برای پروژه جاوااسکریپت و Next.js

برای فرانت‌اند و نود، منطق همان است، فقط ابزارها عوض می‌شود:

name: JS CI
on: [push, pull_request]
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
          cache: 'npm'
      - run: npm ci
      - run: npm run lint
      - run: npm run build
      - run: npm test -- --coverage

نصب، Lint و Build خودکار

همیشه از npm ci به‌جای npm install در CI استفاده کن؛ چون دقیقاً از روی package-lock.json نصب می‌کند و قابل تکرار است. اگر از pnpm یا yarn استفاده می‌کنی، اکشن‌های pnpm/action-setup و cache-dependency-path را فعال کن.

اجرای تست با Vitest و ارسال Coverage

برای پروژه‌های Vite و Next.js، Vitest جایگزین سبک و سریع Jest است. می‌توانی Coverage را به Codecov یا SonarCloud بفرستی و حتی اگر Coverage زیر ۸۰٪ بود، PR را فیل کنی:

- name: Check coverage threshold
  run: |
    COV=$(jq .total.lines.pct coverage/coverage-summary.json)
    if (( $(echo "$COV < 80" | bc -l) )); then echo "Coverage too low: $COV%"; exit 1; fi

دیپلوی خودکار؛ از GitHub تا سرور و Vercel

CI بدون CD نصف کار است. وقتی تست‌ها سبز شدند، وقتش است کد را خودکار به سرور بفرستی.

دیپلوی با SSH و rsync به VPS

ساده‌ترین روش برای یک VPS اوبونتو:

deploy:
  needs: test
  if: github.ref == 'refs/heads/main'
  runs-on: ubuntu-latest
  steps:
    - uses: actions/checkout@v4
    - name: Deploy via SSH
      uses: appleboy/ssh-action@v1
      with:
        host: ${{ secrets.SSH_HOST }}
        username: ${{ secrets.SSH_USER }}
        key: ${{ secrets.SSH_KEY }}
        script: |
          cd /opt/myapp
          git pull origin main
          uv sync
          systemctl restart myapp

نکته امنیتی: هرگز کلید SSH را در کد ننویس. آن را در Settings > Secrets and variables > Actions به‌عنوان Secret ذخیره کن و با secrets.SSH_KEY بخوان.

دیپلوی خودکار به Vercel و Docker Hub

اگر پروژه‌ات Next.js است، Vercel به‌صورت پیش‌فرض با هر push دیپلوی می‌کند، اما با Action رسمی‌اش کنترل بیشتری داری:

- name: Deploy to Vercel
  uses: amondnet/vercel-action@v25
  with:
    vercel-token: ${{ secrets.VERCEL_TOKEN }}
    vercel-org-id: ${{ secrets.ORG_ID }}
    vercel-project-id: ${{ secrets.PROJECT_ID }}
    scope: ${{ secrets.VERCEL_SCOPE }}

برای بک‌اند داکری، یک Job دیگر بساز که ایمیج را بیلد و به Docker Hub پوش کند، سپس روی سرور docker pull بزند. این الگو مخصوصاً برای میکروسرویس‌ها عالی است.

ترفندهای حرفه‌ای و امنیت در GitHub Actions

وقتی پایپ‌لاین پایه را راه انداختی، این ترفندها تو را از آماتور به حرفه‌ای می‌برد:

استفاده از Secrets و Environment Protection

Secrets را دسته‌بندی کن: برای staging و production دو Environment جدا بساز و هر کدام Secrets مخصوص خودش را داشته باشد. با environment: production در Job، گیت‌هاب قبل از اجرا تأیید دستی می‌خواهد.
محدود کردن دسترسی GITHUB_TOKEN: به‌صورت پیش‌فرض توکن دسترسی نوشتن دارد. با permissions: contents: read آن را فقط خواندنی کن تا اگر Action مخربی اضافه شد، نتواند به ریپو آسیب بزند.
پین کردن نسخه Actionها: به‌جای @v4 از هش کامیت مثل @a81a0ae استفاده کن تا اگر نگهدارنده Action هک شد، پایپ‌لاین تو آلوده نشود.

ماتریس بیلد و اجرای موازی برای چند نسخه پایتون/نود

می‌خواهی مطمئن شوی کدت روی پایتون ۳.۱۰ تا ۳.۱۲ و روی اوبونتو و ویندوز کار می‌کند؟ ماتریس بساز:

jobs:
  test:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [ubuntu-latest, windows-latest]
        python-version: ["3.10", "3.11", "3.12"]
        exclude:
          - os: windows-latest
            python-version: "3.10"
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: ${{ matrix.python-version }}
      - run: pytest

این ماتریس ۵ Job موازی می‌سازد و هر کدام روی ترکیب متفاوتی تست می‌گیرد. اگر یکی فیل شد، سریع می‌فهمی کدام نسخه مشکل دارد. همین الگو برای نود ۱۸ و ۲۰ و ۲۲ هم کاربرد دارد.

خطاهای رایج و عیب‌یابی سریع

سه خطایی که تقریباً همه اول کار می‌بینند:

فایل YAML Indentation اشتباه: YAML به فاصله حساس است. از یک Linter آنلاین YAML قبل از پوش استفاده کن. ارور mapping values are not allowed here معمولاً همین است.
کش قدیمی و تست‌های فیک سبز: اگر وابستگی عوض شده ولی کش قدیمی برگردانده می‌شود، کلید کش را عوض کن یا actions/cache را با cache-dependency-path دقیق کن.
Secrets در دسترس نیست در Fork PRها: به‌دلایل امنیتی، Secrets در PRهای از Fork در دسترس نیست. برای این حالت از pull_request_target با احتیاط استفاده کن یا بررسی را به Job جداگانه منتقل کن.

برای دیباگ، تب Actions > Enable debug logging را فعال کن یا در Workflow اضافه کن:

env:
  ACTIONS_STEP_DEBUG: true
  ACTIONS_RUNNER_DEBUG: true

سوالات متداول

آیا GitHub Actions رایگان است؟

برای ریپازیتوری‌های عمومی کاملاً رایگان و نامحدود است. برای ریپازیتوری‌های خصوصی، هر ماه ۲۰۰۰ دقیقه اجرای رایگان روی Runner لینوکسی (معادل حدود ۳۳ ساعت) و ۵۰۰ مگابایت فضای Artifact داری. برای اکثر پروژه‌های شخصی و استارتاپی همین مقدار کافی است و اگر تمام شد، هزینه‌اش از ۰.۰۰۸ دلار برای هر دقیقه شروع می‌شود.

فرق Workflow و Action چیست؟

Workflow یک پایپ‌لاین کامل است که تو در فایل YAML می‌نویسی و می‌گویی چه زمانی و چه مراحلی اجرا شود، اما Action یک بلوک آماده قابل استفاده مجدد داخل آن Workflow است. مثلاً actions/checkout یک Action است که کد را کلون می‌کند، در حالی که فایل ci.yml که شامل چند Action و دستور است، یک Workflow محسوب می‌شود.

چطور جلوی اجرای بیهوده Workflow را بگیرم؟

با فیلترهای paths و paths-ignore فقط روی تغییر فایل‌های مرتبط اجرا کن، با if: github.ref == 'refs/heads/main' دیپلوی را فقط روی شاخه اصلی محدود کن، از concurrency برای لغو اجرای قبلی وقتی پوش جدید آمد استفاده کن، و کش وابستگی‌ها را فعال نگه دار تا هر اجرا سریع‌تر و ارزان‌تر شود.

جمع‌بندی؛ از این به بعد هر Push خودکار تست می‌شود

دیدی که GitHub Actions فقط یک ابزار CI/CD نیست؛ یک همکار خستگی‌ناپذیر است که شب و روز مراقب کیفیت کدت است. با یک فایل YAML ساده شروع کردی، بعد کش و ماتریس و Secrets را اضافه کردی و در نهایت پایپ‌لاینی ساختی که با هر پوش، کد پایتون یا جاوااسکریپت را لینت و تست می‌کند و در صورت موفقیت، خودکار به سرور یا Vercel دیپلوی می‌کند.

پیشنهاد عملی: همین امروز برای یک پروژه کوچک، فایل .github/workflows/ci.yml را بساز و فقط اجرای pytest یا npm test را خودکار کن. هفته بعد، Ruff و کش و سپس دیپلوی را اضافه کن. بعد از یک ماه، دیگر نمی‌توانی بدون تیک سبز گیت‌هاب کد بزنی. اگر می‌خواهی سرعت نصب پایتون را هم به حداکثر برسانی، بد نیست نگاهی به آموزش uv بیندازی و مدیریت وابستگی‌ها را هم مدرن کنی.

آموزش GitHub Actions از صفر؛ ساخت پایپ‌لاین CI/CD خودکار برای پایتون و جاوااسکریپت