GitHub Code Quality چیست؟ راهنمای کامل کنترل کیفیت کد قبل از Merge

افزایش سرعت تولید کد، مخصوصاً با ابزارهای هوش مصنوعی، یک مشکل تازه ایجاد کرده است: تیم می تواند سریع تر Feature بسازد، اما همان سرعت ممکن است بدهی فنی، خطاهای نگه داری و رفتارهای غیرقابل اعتماد را هم بیشتر کند. GitHub Code Quality تلاش می کند این فاصله را داخل همان Pull Request پر کند؛ یعنی قبل از Merge، مشکل را روی خط مربوط نشان دهد، دلیلش را توضیح دهد، اثر آن بر پوشش تست را نمایش دهد و در بعضی موارد اصلاح پیشنهادی آماده کند.

GitHub Code Quality دقیقاً چیست؟

GitHub Code Quality یک محصول مستقل برای پیدا کردن مشکلات «قابلیت نگه داری» و «قابلیت اطمینان» در کد است. قابلیت نگه داری یعنی تغییر، فهم و توسعه کد در ماه های بعد چقدر دشوار خواهد بود. قابلیت اطمینان هم به این مربوط است که کد در شرایط واقعی چقدر رفتار قابل پیش بینی دارد. این دو مفهوم با آسیب پذیری امنیتی یکسان نیستند؛ ممکن است کدی از نظر امنیتی آسیب پذیر نباشد، اما به خاطر شرط های پیچیده، مدیریت خطای ناقص یا ساختار شکننده، احتمال Bug بالایی داشته باشد.

محصول در دو نقطه اجرا می شود. نقطه اول Pull Request است؛ یعنی زمانی که تغییر هنوز وارد شاخه اصلی نشده و اصلاح آن کم هزینه تر است. نقطه دوم شاخه پیش فرض مخزن است؛ جایی که می تواند بدهی کیفیتی موجود را پیدا کند و به تیم برای پاک سازی تدریجی آن دید بدهد. این تفکیک مهم است، چون مدیریت کیفیت فقط جلوگیری از مشکل تازه نیست؛ تیم های قدیمی معمولاً باید با سال ها کد انباشته نیز کنار بیایند.

GitHub این قابلیت را در 20 ژوئیه 2026 برای پلن های Team و Enterprise Cloud عمومی کرد. محصول در زمان عرضه برای GitHub Enterprise Server در دسترس نبود و به صورت مستقل از GitHub Advanced Security فروخته می شود. بنابراین فعال بودن Advanced Security به تنهایی به معنی داشتن Code Quality نیست و تیم باید جداگانه هزینه و سیاست فعال سازی آن را بررسی کند.

ارزش اصلی Code Quality این نیست که تعداد بیشتری Warning بسازد؛ ارزش آن زمانی ایجاد می شود که بازخورد درست، در همان لحظه ای برسد که توسعه دهنده هنوز زمینه تغییر را به خاطر دارد.

تحلیل ترکیبی CodeQL و هوش مصنوعی چگونه کار می کند؟

Code Quality فقط یک مدل هوش مصنوعی نیست. بخش اول آن از تحلیل قطعی CodeQL استفاده می کند. «تحلیل قطعی» یعنی یک Query مشخص، الگوی تعریف شده ای را در کد جست وجو می کند و در شرایط یکسان باید نتیجه قابل تکراری بدهد. این روش برای Anti-patternهای شناخته شده مناسب است؛ مثلاً مقایسه اشتباه یک مقدار، شاخه شرطی بی اثر، کد غیرقابل دسترسی یا الگویی که نگه داری را سخت می کند.

بخش دوم، تحلیل هوش مصنوعی است. این لایه برای موقعیت هایی مفید است که مشکل را نمی توان همیشه با یک Query ثابت و محدود توضیح داد. مدل می تواند تغییرات تازه را در متن اطرافشان بخواند، رابطه بخش ها را بفهمد و ایرادهایی را پیشنهاد کند که هنوز برایشان Rule آماده وجود ندارد. طبق مستندات GitHub، این تحلیل می تواند روی زبان هایی فراتر از فهرست رسمی CodeQL نیز کار کند، هرچند سطح قطعیت و نوع پوشش آن با قواعد قطعی یکسان نیست.

ترکیب این دو روش از نظر مهندسی مهم است. اگر همه چیز به هوش مصنوعی سپرده شود، خروجی ممکن است ناپایدار یا بیش ازحد تفسیری شود. اگر فقط Rule داشته باشیم، مشکلات تازه و وابسته به Context از دست می روند. Code Quality تلاش می کند مسئله های روشن را با CodeQL و مسئله های Contextمحور را با تحلیل AI بپوشاند. بااین حال، تیم باید یافته AI را «پیشنهاد قابل بررسی» بداند، نه حکم قطعی.

داخل Pull Request چه چیزی می بینیم؟

وقتی Pull Request باز می شود، Code Quality می تواند یافته را به صورت Comment روی خط مربوط ثبت کند. توسعه دهنده به جای رفتن به یک داشبورد جدا، همان جا شرح مشکل، شدت و پیشنهاد اصلاح را می بیند. این نزدیکی به جریان کار اهمیت زیادی دارد؛ زیرا احتمال اینکه Warning فراموش شود یا به یک Backlog بی انتها منتقل شود کمتر می شود.

یافته های Rule-based با حساب github-code-quality[bot] نمایش داده می شوند و شدت هایی مانند Error، Warning و Note دارند. شدت به تیم کمک می کند تصمیم بگیرد کدام مورد باید قبل از Merge حل شود و کدام مورد می تواند بعداً بررسی شود. اما شدت به تنهایی کافی نیست؛ Context پروژه، حساسیت مسیر اجرا، سابقه خطا و هزینه اصلاح هم باید وارد تصمیم شوند.

Copilot Autofix برای برخی یافته ها اصلاح پیشنهادی می سازد. «Autofix» یعنی سیستم فقط ایراد را نام نمی برد؛ Patch پیشنهادی ارائه می کند که توسعه دهنده می تواند مرور کند و در صورت مناسب بودن اعمال کند. این فرایند همچنان Review انسانی می خواهد. اصلاح خودکار ممکن است Syntax را درست کند، اما درک کامل Business Rule، قراردادهای داخلی و اثر جانبی تغییر همیشه تضمین شده نیست.

یک سناریوی واقعی

فرض کنید یک Pull Request در سرویس پرداخت، یک شرط پیچیده برای تشخیص وضعیت تراکنش اضافه کرده است. CodeQL ممکن است شاخه ای را پیدا کند که عملاً هیچ وقت اجرا نمی شود. تحلیل AI نیز می تواند متوجه شود که دو وضعیت نزدیک، پیام خطای یکسان ولی رفتار متفاوت دارند. هم زمان، گزارش پوشش تست نشان می دهد مسیر جدید هیچ Testی ندارد. در این حالت Code Quality سه نوع سیگنال می دهد: مشکل ساختاری، ابهام Contextمحور و افت پوشش تست. تصمیم نهایی همچنان با تیم است، اما اطلاعات لازم در یک نقطه جمع شده اند.

اسکن شاخه پیش فرض چه فایده ای دارد؟

Pull Request فقط از ورود بدهی تازه جلوگیری می کند. بسیاری از تیم ها پیش از فعال سازی Code Quality هزاران فایل و سال ها تغییر در شاخه اصلی دارند. اسکن شاخه پیش فرض برای همین وضعیت طراحی شده است. یافته های موجود در داشبورد جمع می شوند و تیم می تواند آن ها را براساس شدت، مخزن و نوع مشکل اولویت بندی کند.

این بخش برای پروژه های Legacy ارزش بیشتری دارد، اما خطر مهمی هم دارد: اگر همه یافته ها یک باره وارد برنامه کاری شوند، تیم با حجم بزرگی از Warning روبه رو می شود و اعتمادش به ابزار کاهش پیدا می کند. راه درست، تعیین Baseline و انتخاب محدوده است. ابتدا باید مشکلات مرتبط با مسیرهای حساس، کد پرتغییر، خطاهای Production و سرویس های حیاتی بررسی شوند. اصلاح فایل هایی که سال ها بدون تغییر مانده اند، همیشه بیشترین بازده را ندارد.

GitHub امکان اعمال Autofix یا سپردن برخی اصلاحات به Copilot cloud agent را نیز توضیح داده است. واگذاری کار به Agent به License مربوط Copilot نیاز دارد و باید با Policy داخلی سازمان هماهنگ شود. تیم هایی که Repository خصوصی، داده حساس یا الزامات Compliance دارند، بهتر است قبل از واگذاری گسترده، نوع داده ارسالی، سطح دسترسی Agent و فرایند Review نهایی را مستند کنند.

پوشش تست و Cobertura چگونه وارد ماجرا می شوند؟

پوشش تست نشان می دهد چه بخشی از کد هنگام اجرای Testها واقعاً اجرا شده است. این معیار به تنهایی کیفیت تست را ثابت نمی کند؛ ممکن است خط اجرا شود، اما Assertion ضعیف باشد. بااین حال، افت ناگهانی Coverage در یک Pull Request سیگنال مهمی است. Code Quality می تواند گزارش Cobertura XML موجود را بخواند و تغییر پوشش را داخل Pull Request نشان دهد.

Cobertura یک قالب XML رایج برای گزارش Coverage است و ابزارهای مختلف می توانند آن را بسازند. نکته کلیدی این است که Code Quality قرار نیست Test Runner پروژه را جایگزین کند؛ Pipeline شما باید Test را اجرا کند و فایل Coverage را تولید کند. سپس GitHub می تواند آن داده را کنار یافته های کیفیت نمایش دهد. بنابراین قبل از فعال سازی Gate پوشش، باید مطمئن شوید گزارش در همه مسیرهای CI پایدار، کامل و قابل مقایسه است.

بهتر است تیم به جای یک عدد جهانی و بی انعطاف، از سیاست متناسب استفاده کند. برای مثال، پروژه ای با Coverage فعلی 45 درصد اگر ناگهان Gate را روی 80 درصد بگذارد، تقریباً همه Pull Requestها مسدود می شوند. سیاست منطقی تر می تواند «پوشش کاهش پیدا نکند» یا «کد تازه حداقل پوشش مشخص داشته باشد» باشد. سپس Threshold به تدریج بالا می رود.

Quality Gate و Ruleset چه تفاوتی ایجاد می کنند؟

تا زمانی که یافته فقط Comment باشد، توسعه دهنده می تواند آن را نادیده بگیرد و Merge انجام دهد. Quality Gate نتیجه تحلیل را به Policy تبدیل می کند. GitHub اجازه می دهد از Ruleset برای تعیین شرط کیفیت و پوشش استفاده شود؛ مثلاً Pull Request دارای یافته Rule-based حل نشده یا Coverage کمتر از آستانه مشخص، اجازه Merge نداشته باشد.

این قابلیت قدرتمند است، اما فعال سازی فوری حالت Block روی همه مخازن معمولاً تصمیم خوبی نیست. GitHub حالت Evaluate را برای rollout تدریجی پیشنهاد می کند. در این حالت تیم می بیند اگر Rule فعال بود، کدام Pull Requestها متوقف می شدند، بدون اینکه جریان واقعی توسعه را قطع کند. چند هفته داده، بهترین Threshold و مهم ترین Ruleها را روشن می کند.

Policy باید استثنا نیز داشته باشد، اما استثنا نباید به مسیر عادی تبدیل شود. برای Hotfix Production شاید عبور کنترل شده لازم باشد. در مقابل، اگر هر تیم به محض دریافت Warning آن را Dismiss کند، سیستم فقط هزینه تولید می کند. دلیل Dismiss، مالک تصمیم و زمان بازبینی باید قابل ردیابی باشد.

داشبورد سازمانی چه دیدی می دهد؟

نسخه عمومی Code Quality امکان فعال سازی سازمانی و داشبورد سطح Organization را اضافه کرده است. مدیر فنی می تواند وضعیت قابلیت نگه داری و قابلیت اطمینان مخازن را یکجا ببیند، Repositoryهای ضعیف تر را پیدا کند و تغییر امتیازها را دنبال کند. این دید برای سازمانی با ده ها یا صدها مخزن از بررسی دستی تک تک Repositoryها بسیار مؤثرتر است.

داشبورد، توزیع امتیازها و جدول مخازن را ارائه می کند. مدیر سازمان همه مخازن فعال را می بیند و سایر اعضا فقط داده Repositoryهایی را مشاهده می کنند که مجوز دسترسی دارند. بااین حال، امتیاز کیفیت نباید مستقیماً به معیار عملکرد فردی تبدیل شود. Repositoryهای قدیمی، زبان، معماری، حجم و سرعت تغییر متفاوت دارند. مقایسه خام دو تیم می تواند نتیجه ناعادلانه و حتی رفتارهای مخرب ایجاد کند.

بهترین استفاده مدیریتی، پیدا کردن روند و ریسک است: کدام پروژه مرتب بدهی تازه می سازد؟ کدام تیم Warningهای بحرانی را پیش از Merge حل می کند؟ کدام مخزن Coverage رو به کاهش دارد؟ این پرسش ها به اقدام مهندسی منتهی می شوند. در مقابل، یک رتبه بندی ساده «بهترین و بدترین تیم» معمولاً Context لازم را از بین می برد.

چه زبان هایی پشتیبانی می شوند؟

تحلیل Rule-based مبتنی بر CodeQL در زمان نگارش برای C#، Go، Java، JavaScript، Python، Ruby و TypeScript اعلام شده است. این فهرست به معنی بی فایده بودن محصول برای زبان های دیگر نیست؛ تحلیل هوش مصنوعی می تواند روی Pull Requestها و کدهای تازه تغییرکرده زبان های بیشتری را بررسی کند. تفاوت مهم این است که پوشش قطعی و مجموعه Ruleها برای همه زبان ها برابر نیست.

اگر پروژه چندزبانه است، باید قبل از خرید گسترده Pilot انجام شود. برای مثال، Backend اصلی ممکن است C# باشد و اسکریپت های Build با Bash نوشته شوند. بخش C# از Ruleهای CodeQL بهره می گیرد، اما کیفیت بازخورد Bash ممکن است بیشتر به AI وابسته باشد. تیم باید خروجی را جداگانه برای هر زبان و نوع Repository اندازه گیری کند.

مدل هزینه GitHub Code Quality دقیقاً چگونه است؟

هزینه Code Quality سه بخش دارد. بخش اول License براساس Committer فعال و یکتا است. GitHub در زمان عرضه قیمت پایه را 10 دلار برای هر Committer فعال در ماه اعلام کرد. Committer زمانی فعال محسوب می شود که در 90 روز گذشته Commit او به Repository دارای Code Quality Push شده باشد. هر فرد در سطح سازمان فقط یک بار شمرده می شود، حتی اگر در چند مخزن فعال باشد؛ حساب های GitHub App bot نیز در این شمارش قرار نمی گیرند.

بخش دوم GitHub Actions Minutes است. اسکن های قطعی CodeQL به صورت Workflow اجرا می شوند و روی Runnerهای میزبانی شده GitHub دقیقه مصرف می کنند. اگر Self-hosted Runner استفاده شود، هزینه دقیقه میزبانی شده اعمال نمی شود، اما هزینه زیرساخت، نگه داری و ظرفیت Runner برعهده خود سازمان است.

بخش سوم AI Credits است. تحلیل های هوش مصنوعی و Autofix از مخزن مشترک AI Credit سازمان مصرف می کنند. طبق مستندات GitHub، هر AI Credit معادل 0٫01 دلار آمریکا است، اما تعداد Credit مصرفی به تعامل و میزان Token بستگی دارد. پس تخمین هزینه فقط با شمارش Developerها کامل نیست؛ حجم Pull Request، تعداد یافته ها، استفاده از Autofix و شدت استفاده از AI هم باید اندازه گیری شود.

برای تحلیل AI و Autofix داشتن Copilot License الزامی نیست، اما قابلیت اختیاری واگذاری اصلاح به Copilot cloud agent به License Copilot نیاز دارد. این تفاوت در بودجه بندی مهم است. ممکن است تیم Code Quality را بخرد و از پیشنهادهای اصلاح استفاده کند، بدون اینکه همه توسعه دهنده ها Copilot داشته باشند؛ اما Agentمحورکردن فرایند هزینه جداگانه می سازد.

چطور GitHub Code Quality را اصولی در تیم فعال کنیم؟

برای یک Repository، مسیر فعال سازی از Settings، بخش Security و صفحه Code quality انجام می شود. در همان صفحه می توان زبان های CodeQL و نوع Runner را انتخاب کرد. در سطح Organization نیز مدیر می تواند همه مخازن، فهرست مشخص یا Repositoryهای مطابق Filter را هدف بگیرد و در صورت نیاز دسترسی را Enforce کند. GitHub هنگام تغییر گسترده، اثر فعال سازی و هزینه را برای بازبینی نشان می دهد.

اما مسیر کلیک کردن ساده ترین بخش است. Rollout درست باید با هدف مشخص شروع شود. آیا مشکل اصلی کاهش Coverage است؟ آیا تیم با کد تولیدشده AI سرعت گرفته ولی Review عقب مانده؟ آیا پروژه Legacy بدهی نگه داری زیادی دارد؟ پاسخ این سؤال تعیین می کند کدام مخزن Pilot شود و چه شاخصی سنجیده شود.

چه Repositoryهایی برای Pilot مناسب اند؟

مخزن Pilot نباید آن قدر ساده باشد که هیچ یافته معناداری تولید نکند و نه آن قدر بحرانی که کوچک ترین اختلال پذیرفتنی نباشد. یک سرویس فعال با Pull Requestهای منظم، Test Pipeline نسبتاً پایدار و تیمی که حاضر است خروجی را دسته بندی کند، انتخاب خوبی است. بهتر است یک پروژه جدید و یک پروژه قدیمی را کنار هم قرار دهید تا تفاوت رفتار ابزار روی بدهی موجود و تغییرات تازه روشن شود.

محدودیت ها و نکات تصمیم گیری

اولین محدودیت، Noise است. هر ابزار تحلیل استاتیک یا AI می تواند یافته کم اهمیت یا نامتناسب با Context پروژه بسازد. اگر تیم بدون تنظیم Policy همه موارد را اجباری کند، سرعت Review پایین می آید و توسعه دهنده ها به مرور همه Commentها را نادیده می گیرند. موفقیت ابزار به کیفیت فرایند Triaging وابسته است.

دومین محدودیت، وابستگی به GitHub Cloud است. محصول در زمان عرضه روی GitHub Team و Enterprise Cloud در دسترس بود و برای Enterprise Server ارائه نشده بود. سازمان هایی که به دلایل مقرراتی یا شبکه بسته از Server استفاده می کنند، باید گزینه های دیگر را بررسی کنند یا منتظر تغییر نقشه راه بمانند.

سومین محدودیت، هزینه متغیر است. تیم کوچک با Pull Request کم ممکن است هزینه قابل کنترلی داشته باشد، اما سازمان بزرگ با هزاران Committer، Workflowهای پرتعداد و Autofix گسترده باید Budget Guardrail بسازد. فعال سازی روی همه Repositoryها بدون Pilot، هم هزینه و هم حجم یافته را ناگهان بالا می برد.

چهارمین محدودیت، جایگاه ابزار در معماری کیفیت است. Code Quality جای Unit Test، Integration Test، تست Load، Observability، Review معماری و بررسی Business Rule را نمی گیرد. این محصول یک لایه بازخورد اضافه است. اگر Pipeline تست ناپایدار باشد یا تیم مالکیت کد مشخصی نداشته باشد، اضافه کردن یک داشبورد جدید مشکل بنیادی را حل نمی کند.

پرسش های متداول درباره GitHub Code Quality

آیا Code Quality همان GitHub Advanced Security است؟

خیر. GitHub Code Quality محصولی مستقل و مکمل ابزارهای امنیتی است. خرید یا فعال سازی Advanced Security به صورت خودکار License این محصول را فراهم نمی کند.

آیا برای Autofix باید GitHub Copilot داشته باشیم؟

برای تحلیل AI و Copilot-powered Autofix داشتن Copilot License الزامی نیست و مصرف از AI Credits سازمان محاسبه می شود. اما واگذاری اصلاح به Copilot cloud agent از قابلیت های اختیاری وابسته به Copilot License است.

آیا Code Quality می تواند Merge را مسدود کند؟

بله. Rulesetها می توانند یافته های Rule-based حل نشده یا نرسیدن Coverage به Threshold را به شرط Merge تبدیل کنند. بهتر است ابتدا Evaluate Mode استفاده شود تا اثر Policy بدون توقف واقعی جریان توسعه سنجیده شود.

آیا برای Coverage باید ابزار تست را عوض کنیم؟

نه لزوماً. اگر Pipeline فعلی گزارش Cobertura XML تولید کند، GitHub می تواند همان گزارش را نمایش دهد. مسئله اصلی، تولید پایدار و صحیح گزارش در CI است.

آیا این محصول فقط برای کد تولیدشده با AI است؟

خیر. تحلیل برای کد انسانی و AI یکسان کاربرد دارد. بااین حال، وقتی سرعت تولید کد بالا می رود، نیاز به Gate و بازخورد خودکار بیشتر می شود؛ به همین دلیل GitHub روی این سناریو تأکید کرده است.

آیا می توان Code Quality را روی همه مخازن سازمان یکجا فعال کرد؟

بله. مدیر سازمان می تواند همه مخازن، Repositoryهای انتخابی یا مخازن مطابق Filter را فعال کند و دسترسی را Enforce کند. بااین حال، Rollout تدریجی برای کنترل هزینه و کیفیت یافته ها انتخاب امن تری است.

جمع بندی سریع

• Code Quality کیفیت و Coverage را پیش از Merge وارد جریان Review می کند.
• ترکیب CodeQL و AI پوشش را بیشتر می کند، اما بررسی انسانی همچنان ضروری است.
• Ruleset و Evaluate Mode ابزار اصلی تبدیل تحلیل به Policy کنترل شده هستند.
• هزینه از License، Actions Minutes و AI Credits تشکیل می شود.
• بهترین شروع، Pilot کوچک با معیارهای روشن و Rollout مرحله ای است.

اگر قصد فعال سازی دارید، از یک Repository نماینده شروع کنید، دو Sprint داده جمع کنید و فقط Ruleهایی را اجباری کنید که واقعاً به تصمیم بهتر و Bug کمتر منتهی می شوند. راهنمای رسمی GitHub Code Quality، صفحه اعلام عرضه عمومی و مستند مدل هزینه نقطه شروع دقیقی برای تصمیم سازمانی هستند.