ابزار act واقعاً یکی از بهترین روش‌هاست برای اجرای workflowهای GitHub Actions به‌صورت محلی، مخصوصاً زمانی که با محدودیت‌های GitHub Free Plan روبه‌رو هستی یا می‌خواهی قبل از commit، workflow را تست کنی.

بیا گام‌به‌گام و با جزئیات بررسی‌اش کنیم 👇

🧩 act چیست؟

act یک ابزار متن‌باز است (ساخته شده با Go) که به تو اجازه می‌دهد:

workflowهای GitHub Actions (یعنی فایل‌های YAML داخل .github/workflows/) را در کامپیوتر خودت، با Docker، اجرا کنی.

در واقع act یک محیط شبیه‌سازی از GitHub Actions ایجاد می‌کند تا همان jobها، همان actionها، و همان eventها را روی سیستم لوکال اجرا کنی.

⚙️ نحوه کار act

1. act فایل .github/workflows/*.yml را می‌خواند.
2. event مورد نظر (مثلاً push, pull_request, یا دستی) را شبیه‌سازی می‌کند.
3. برای هر job، یک container Docker ایجاد می‌کند.
4. همان دستورات runs-on: ubuntu-latest را داخل آن container اجرا می‌کند.
5. نتیجه را در ترمینال نمایش می‌دهد.

بنابراین act یک mini-GitHub Actions runner است که کاملاً روی سیستم خودت اجرا می‌شود.

💻 نصب act

macOS / Linux

brew install act

Windows

scoop install act

یا:

choco install act-cli

نسخه دستی (Cross-platform)

curl -s https://raw.githubusercontent.com/nektos/act/master/install.sh | sudo bash

🚀 اجرای workflow

در ریشه مخزن خود (که پوشه .github/workflows/ دارد):

act

به‌صورت پیش‌فرض act event push را اجرا می‌کند.

اگر بخواهی event دیگری را تست کنی:

act pull_request
act workflow_dispatch

یا برای اجرای job خاص:

act -j test

⚡️ Docker Image های Runner

GitHub runners معمولاً Ubuntu-latest یا Windows هستند. act از imageهای Docker برای شبیه‌سازی آنها استفاده می‌کند.

سه نوع image اصلی وجود دارد:

نمونه دستور برای انتخاب image:

act -P ubuntu-latest=catthehacker/ubuntu:act-latest

🔒 مدیریت Secrets

می‌توانی secrets را به صورت محلی تعریف کنی:

1. ایجاد فایل .secrets در ریشه پروژه:

   GITHUB_TOKEN=abc123
   DB_PASSWORD=secret
   

2. اجرای act با secrets:

   act --secret-file .secrets
   

یا مستقیماً در محیط:

act -s GITHUB_TOKEN=abc123

🧠 ویژگی‌های جالب act

⚠️ محدودیت‌ها و نکات مهم

• بعضی actionها که به GitHub API متصل‌اند (مثل actions/checkout@v4) نیاز به token دارند.
• act فقط روی سیستم‌هایی که Docker دارند کار می‌کند.
• بعضی runnerهای خاص (مثلاً windows-latest) شبیه‌سازی نمی‌شوند.
• اگر workflow پیچیده باشد (مثل matrix یا multiple jobs)، act آن را به‌صورت sequential اجرا می‌کند (نه parallel).

🧰 مثال واقعی

فرض کن workflow زیر را داری:

# .github/workflows/test.yml
name: Test

on: [push]

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run tests
        run: pytest tests/

می‌توانی آن را به سادگی در لوکال اجرا کنی:

act -j build

💡 جمع‌بندی

اگر بخواهی، می‌توانم برایت یک نمونه فایل workflow مخصوص پروژه Odoo بنویسم که با act سازگار باشد (مثلاً نصب Odoo، تست addonها، و دسترسی به مخزن خصوصی).

آیا می‌خواهی نمونه‌ی واقعی برای پروژه‌ات آماده کنم؟