‏انتشار خودکار پکیج npm با GitHub Actions

ابزارهایی مثل release-it این امکان رو می‌دن که ورژن پکیج رو بر اساس پیام‌های کامیت (طبق استاندارد Conventional Commits) به‌صورت خودکار بالا ببری، چنج‌لاگ تولید کنی، گیت‌تگ بزنی و پکیج رو روی npm منتشر کنی. معمولاً این فرآیند به‌صورت دستی روی ماشین محلی اجرا می‌شه، اما وصل کردنش به GitHub Actions خیلی راحت‌تره.

برای راه‌اندازی احراز هویت با npm، روش پیشنهادی استفاده از Trusted Publisher با پروتکل OIDC هست. در تنظیمات پکیج روی npmjs.com، گزینه GitHub Actions رو به‌عنوان ناشر معتمد تعریف می‌کنی و مسیر فایل workflow رو مشخص می‌کنی. این روش دیگه نیازی به توکن npm نداره و از آنجا که توکن‌های قدیمی npm فقط ۹۰ روز اعتبار دارن، استفاده از Trusted Publisher برای workflows خودکار خیلی منطقی‌تره.

برای پوش کردن کامیت ریلیز به ریپازیتوری (مخصوصاً اگه شاخه محافظت‌شده داری)، به یه Personal Access Token با دسترسی خواندن/نوشتن روی محتوای ریپو نیاز داری. توصیه می‌شه این توکن رو داخل یه «Environment» به اسم release ذخیره کنی و دسترسی اون رو فقط به شاخه main محدود کنی تا از سوءاستفاده جلوگیری بشه.

ساختار کلی workflow شامل دو جاب هست: اول چک می‌کنه که کامیت جاری خودش یه کامیت ریلیز نباشه (تا از حلقه بی‌نهایت جلوگیری بشه)، بعد release-it رو اجرا می‌کنه. این workflow روی رویداد workflow_run تنظیم می‌شه تا فقط بعد از موفق شدن workflow اصلی CI (تست‌ها و لینتینگ) اجرا بشه:

on:
  workflow_run:
    workflows: ["CI"]
    types:
      - completed
    branches:
      - main

از نظر امنیتی چند نکته مهم وجود داره: مجوز id-token: write رو فقط به جاب publish بده، نه به کل workflow. از کش وابستگی‌ها در جاب ریلیز استفاده نکن چون یه کش آلوده می‌تونه کد مخرب رو وارد فرآیند انتشار کنه. اکشن‌های third-party رو به جای تگ (@v3) به SHA کامل کامیت پین کن تا از حملات زنجیره تأمین در امان بمونی.

نکات کلیدی:

• release-it با Conventional Commits ورژن‌دهی و چنج‌لاگ رو خودکار می‌کنه
• احراز هویت از طریق OIDC (Trusted Publisher) امن‌تر از توکن npm هست
• توکن‌های npm از نوامبر ۲۰۲۵ فقط ۹۰ روز اعتبار دارن
• برای جلوگیری از حلقه بی‌نهایت، workflow باید کامیت‌های ریلیز رو تشخیص بده و از اجرای مجدد صرف‌نظر کنه
• پین کردن اکشن‌ها به commit SHA به جای تگ، یه لایه امنیتی مهم اضافه می‌کنه
• پکیج‌های جدید باید اول از ماشین محلی منتشر بشن؛ Trusted Publishing فقط برای نسخه‌های بعدی کار می‌کنه