رفع خطای GitHub Actions؛ از Workflow Run تا Job Log و اجرای مجدد امن

چراغ قرمز GitHub Actions به‌تنهایی علت خرابی را نمی‌گوید. ممکن است Workflow اصلاً به‌خاطر فیلتر رویداد اجرا نشده باشد، یک Job به شرط if رد شده باشد، Runner پیش از اجرای آزمون‌ها مشکل پیدا کرده باشد یا آزمون واقعاً شکست خورده باشد. این راهنما یک مسیر ثابت برای تشخیص ارائه می‌کند: Run درست را پیدا کنید، Job و نخستین Step مسئله‌دار را جدا کنید، از Log شواهد بردارید و بازآزمایی را طوری انجام دهید که معلوم باشد چه چیزی تغییر کرده است.

اول مسئله را درست نام‌گذاری کنید

در صفحه Pull Request یا تب Actions، سه حالت را با هم یکی نگیرید: Run وجود ندارد، Run شروع شده ولی Job اجرا نشده، یا Job اجرا شده و شکست خورده است. برای حالت نخست دنبال Log نگردید؛ در فایل Workflow، رویداد on، شاخه هدف، فیلتر مسیرها و وضعیت مجوز اجرای Workflow را بررسی کنید. برای حالت دوم شرط‌های Job و وابستگی needs را بخوانید. فقط در حالت سوم Log Step محل اصلی جست‌وجوی خطاست. راهنمای عیب‌یابی GitHub نیز بررسی رویداد، شرط و اجرای واقعی را از هم جدا می‌کند.

شناسه یا URL همان Run، نام Workflow، نام شاخه، commit و رویداد محرک را ثبت کنید. وقتی چند commit پشت‌سرهم روی یک Pull Request می‌آیند، بازکردن آخرین Run به‌جای Run مربوط به پیام خطا تشخیص را منحرف می‌کند. همچنین وضعیت «Cancelled» را خطای آزمون تعبیر نکنید؛ ممکن است اجرای تازه‌تر، اجرای قبلی را به‌خاطر سیاست هم‌زمانی متوقف کرده باشد.

مثال فرضی: آزمون سبز محلی، CI قرمز

فرض کنید آزمون‌های پروژه روی لپ‌تاپ اجرا می‌شوند، اما Job در GitHub Actions در مرحله نصب وابستگی شکست می‌خورد. نتیجه معتبر این نیست که خود آزمون ناسازگار است؛ هنوز حتی به Step آزمون نرسیده‌اید. نسخه runtime، فایل lock، دسترسی شبکه و پیام خطای نصب را بررسی کنید. در حالت دیگر ممکن است نصب موفق باشد و نخستین شکست در آزمون مرورگر رخ دهد؛ آن وقت باید محیط آزمون و خروجی همان Step را بخوانید. این دو مورد سناریوی آموزشی‌اند، نه نتیجه آزمایشی روی مخزن واقعی شما.

از Run به Job و نخستین Step خطادار برسید

در تب Actions، Workflow و Run مربوط به همان commit را باز کنید. نمای گرافی Run نشان می‌دهد کدام Job موفق، شکست‌خورده، ردشده یا در انتظار است. روی Job شکست‌خورده بروید و Stepها را از بالا مرور کنید. معمولاً نخستین خطای مشخص، از پیام نهایی «Process completed with exit code» ارزش تشخیصی بیشتری دارد؛ آن پیام فقط می‌گوید فرایند با کد غیرصفر تمام شده است. مستندات Logهای اجرای GitHub مسیر مشاهده، جست‌وجو و دریافت Log هر Job را توضیح می‌دهد.

برای هر فرضیه، سه جزء بنویسید: Step، قطعه کوتاه و غیرحساس از خطای اصلی، و تفاوت آن با اجرای سبز قبلی. برای مثال «Job build، Step نصب، فایل lock با نسخه بسته سازگار نیست». این یادداشت از جمله مبهم «CI خراب است» مفیدتر است. اگر Log طولانی است، فقط همان Job را جست‌وجو کنید و از بالاترین خطای مرتبط به پایین بروید؛ خطاهای بعدی ممکن است آبشاری باشند.

از Log چه چیزی را عمومی نکنیم؟

پیش از چسباندن Log در Issue یا پیام، نشانی‌های خصوصی، توکن‌ها، نام متغیرهای حساس و اطلاعات مشتری را بازبینی کنید. پنهان‌سازی خودکار Secret در همه شکل‌های تغییر‌یافته یا داده‌هایی که اصلاً به‌عنوان Secret تعریف نشده‌اند تضمین کامل نیست. اگر خروجی باید با هم‌تیمی به‌اشتراک گذاشته شود، خلاصه خطا و گام بازتولید را ترجیح دهید و دسترسی به آرشیو کامل Log را به افراد لازم محدود نگه دارید. راهنمای استفاده امن GitHub Actions بر حداقل دسترسی و احتیاط با ورودی نامطمئن تأکید می‌کند.

چهار شاخه رایج عیب‌یابی

Workflow اصلاً شروع نمی‌شود

نام فایل و قرارگرفتن آن در مسیر Workflow مخزن را بررسی کنید، سپس رویداد محرک را با کاری که انجام داده‌اید تطبیق دهید. آیا Workflow فقط برای push روی شاخه اصلی تعریف شده، ولی شما Pull Request باز کرده‌اید؟ آیا فیلتر paths یا branches تغییر شما را کنار گذاشته است؟ آیا اجرای کد از fork نیاز به تأیید دارد؟ به‌جای تغییر چند شرط در یک نوبت، یک علت را مشخص کنید و نتیجه Run تازه را ببینید. مرجع syntax رسمی قواعد رویداد و فیلترها را شرح می‌دهد.

Job رد می‌شود یا منتظر می‌ماند

در نمای گراف ببینید Job به کدام Job دیگر وابسته است و شرط if آن چه می‌خواهد. ردشدن یک Job به‌دلیل شرط، شکست آزمون نیست. اگر Job در انتظار Runner می‌ماند، برچسب Runner و ظرفیت محیط اجرا را بررسی کنید. برای self-hosted Runner، وضعیت آنلاین و دسترسی آن به مخزن مهم است؛ بدون شواهد، خطای کد را علت صف‌ماندن Job ندانید. زمان شروع، نام Runner و پیام انتظار را در گزارش مسئله ثبت کنید.

Step نصب یا build شکست می‌خورد

نسخه زبان و ابزار، فایل lock، مسیر کاری و وابستگی‌های سیستم را با اجرای سبز قبلی مقایسه کنید. اگر خطا فقط روی CI است، تفاوت محیط را فهرست کنید: سیستم‌عامل، نسخه runtime، متغیر محیط، cache و دسترسی به سرویس بیرونی. پاک‌کردن همه cacheها یا به‌روزکردن همه بسته‌ها به‌طور هم‌زمان ممکن است علامت را پنهان کند و علت را مبهم بگذارد. یک تغییر کوچک و قابل‌بازگشت انجام دهید و با Run تازه نتیجه را بسنجید.

Step آزمون یا استقرار شکست می‌خورد

برای آزمون، خروجی assertion و در صورت وجود گزارش یا artifact را بررسی کنید؛ تفاوت شکست پایدار و ناپایدار را با چند Run و همان commit بسنجید. برای استقرار، مجوز GITHUB_TOKEN، Secretهای لازم و دامنه دسترسی محیط را با اصل حداقل دسترسی مرور کنید. افزایش کورکورانه مجوز توکن پاسخ مناسبی به خطای مبهم نیست. اگر Workflow کد Pull Request نامطمئن را اجرا می‌کند، به‌خصوص هنگام استفاده از pull_request_target، قبل از دسترسی دادن به Secret یا توکن پرمجوز، مدل تهدید را بازبینی کنید. یک راه میان‌بر امنیتی می‌تواند مشکل بزرگ‌تری از CI قرمز بسازد.

چه وقت Re-run کمک می‌کند؟

GitHub امکان اجرای مجدد همه Jobها، Jobهای ناموفق یا یک Job مشخص را می‌دهد. اگر علت احتمالی موقتی است، مانند قطع کوتاه‌مدت سرویس بیرونی، بازاجرای فقط Job ناموفق آزمونی مفید است. اگر فایل Workflow یا کد را اصلاح کرده‌اید، بازاجرای Run قدیمی جای Run مربوط به commit جدید را نمی‌گیرد. شناسه attempt و commit هر نتیجه را کنار هم ثبت کنید تا «پس از اصلاح سبز شد» با «همان کد در بار دوم سبز شد» اشتباه نشود.

اگر آزمون ناپایدار است، یک سبز تصادفی مشکل را حل نمی‌کند. الگوی خطا، زمان اجرا، وابستگی به ترتیب آزمون‌ها و داده مشترک را بررسی کنید. Re-run ابزار تشخیص است، نه مجوز عبور از کنترل کیفیت. برای Pull Request، وضعیت نهایی باید به commit و شرط‌های لازم مخزن مربوط باشد.

Debug Logging را هدفمند و کوتاه‌مدت به‌کار ببرید

وقتی Log عادی Step کافی نیست، GitHub امکان Step debug و Runner diagnostic logging را توضیح می‌دهد. در بازاجرای UI نیز می‌توان Debug Logging را برای همان تلاش فعال کرد. این داده بیشتر، امکان تشخیص را بالا می‌برد اما حجم و حساسیت Log را هم افزایش می‌دهد. پیش از فعال‌سازی، دسترسی خواندن Log و مسیر اشتراک‌گذاری آن را بدانید؛ پس از بررسی، خروجی کامل را بی‌محابا در کانال عمومی منتشر نکنید.

اگر به‌جای بازاجرای محدود، متغیر یا Secret تنظیم می‌کنید، درباره ماندگاری آن و تقدم Secret بر Variable آگاه باشید. مقاله حاضر توصیه نمی‌کند به‌صورت دائمی Debug را برای همه Workflowها روشن بگذارید. ابتدا پرسش دقیق داشته باشید؛ مثلاً «چرا Runner این ابزار را پیدا نمی‌کند؟» و بعد فقط اطلاعات مربوط به همان پرسش را بخوانید.

چک‌لیست گزارش یک خطای قابل‌پیگیری

1. نام Workflow، URL یا شناسه Run، attempt، commit و رویداد محرک را ثبت کنید.
2. مشخص کنید Run غایب است، Job رد/منتظر است یا Step واقعاً شکست خورده است.
3. نخستین Step خطادار و پیام مرتبط را بدون داده حساس خلاصه کنید.
4. آخرین اجرای سبزِ قابل‌مقایسه را پیدا کنید و تفاوت محیط یا ورودی را بنویسید.
5. برای هر علت احتمالی یک آزمون مشخص و قابل‌برگشت تعریف کنید.
6. اگر تغییری در کد لازم است، commit تازه و Run تازه را با اجرای قبلی مقایسه کنید.
7. اگر فقط احتمال خطای موقت می‌دهید، Job ناموفق را هدفمند Re-run کنید و attempt را ثبت کنید.
8. Debug Logging را فقط وقتی Log عادی کافی نیست و با مراقبت از دسترسی و داده حساس استفاده کنید.
9. پس از سبزشدن، سناریوی شکست را به آزمون، مستندات یا کنترل CI قابل‌تکرار تبدیل کنید.

برای نمونه، اگر خطا در آزمون مرورگر است، گزارش trace و locator می‌تواند علت را دقیق‌تر از پیام کلی timeout نشان دهد. راهنمای تست End-to-End با Playwright این بخش را جداگانه توضیح می‌دهد؛ اما ابتدا مطمئن شوید که Workflow اصلاً به Step اجرای Playwright رسیده است.

پرسش‌های متداول

از کدام Log شروع کنم؟

Run همان commit را باز کنید، Job ناموفق را پیدا کنید و نخستین Step دارای خطای مرتبط را بخوانید. پیام پایانی exit code اغلب فقط خلاصه پیامد است.

آیا Re-run failed jobs کد اصلاح‌شده را اجرا می‌کند؟

خیر. بازاجرای Run قدیمی برای بررسی همان وضعیت است. پس از اصلاح کد یا Workflow، commit تازه بفرستید و Run تازه را با شناسه جداگانه مقایسه کنید.

چه وقت Debug Logging لازم است؟

وقتی Log معمولی برای تشخیص Runner یا Step کافی نیست. آن را محدود، با توجه به دسترسی و احتمال ثبت اطلاعات حساس به‌کار ببرید و خروجی را پیش از اشتراک‌گذاری بررسی کنید.

اگر Workflow اصلاً اجرا نشده چه کنم؟

رویداد، شاخه هدف، فیلتر مسیرها، شرط‌ها و قواعد تأیید Pull Request را بررسی کنید. نبود Run با شکست Job متفاوت است.

جمع‌بندی و گام بعدی

عیب‌یابی GitHub Actions از یک خط قرمز به یک پرسش قابل‌آزمون تبدیل می‌شود: کدام Run، کدام Job، کدام Step و با چه تفاوتی نسبت به اجرای سالم؟ پس از پیدا‌کردن علت، اصلاح کد را با Run تازه و خطای موقت را با Re-run هدفمند بسنجید. Log بیشتر همیشه بهتر نیست؛ کیفیت شواهد و حفظ داده حساس مهم‌تر است. نتیجه را طوری ثبت کنید که نفر بعدی بتواند همان مسیر را بدون حدس دوباره طی کند.

در اجرای ناموفق بعدی، شناسه Run و نخستین Step خطادار را ثبت کنید، یک فرضیه مشخص بسازید و تنها پس از اصلاح یا بازآزمایی هدفمند نتیجه را با اجرای قبلی مقایسه کنید.