GitHub غيّر طول التوكن: افحص تطبيقك قبل 27 أبريل

لو تطبيقك بيتعامل مع GitHub App installation token كأنه 40 حرفًا ثابتًا، عندك فحص صغير لازم يتعمل النهارده قبل ما التكامل يقع في الإنتاج.

مستوى القارئ: متوسط

المشكلة باختصار

GitHub أعلن في 24 أبريل 2026 أنه سيبدأ من 27 أبريل 2026 طرح صيغة جديدة لتوكنات GitHub App installation. التغيير الأساسي إن التوكن الجديد أطول بكثير، وقد يصل تقريبًا إلى 520 حرفًا بدل افتراض 40 حرفًا عند بعض الأنظمة القديمة. الصيغة ستظل تبدأ بـ ghs_، لكن شكلها سيصبح أقرب إلى ghs_APPID_JWT.

الخبر مهم للمطور العربي لأنه يلمس أدوات بنستخدمها يوميًا: GitHub Actions، Dependabot، Slack integrations، Teams، وأي GitHub App خاص بالشركة. لو عندك SaaS بيسحب repos أو يعلّق على pull requests أو يعمل checks، المشكلة مش في GitHub نفسه. المشكلة في الكود اللي افترض إن التوكن قصير أو قابل للفهم.

مثال واضح قبل التفاصيل

افترض إن عندك خدمة بتخزّن توكن GitHub App في جدول integrations. المطور القديم كتب العمود كده لأنه شاف التوكنات كلها قصيرة:

ALTER TABLE integrations
ADD COLUMN github_token VARCHAR(64);

الكود كان شغال سنين. فجأة التوكن الجديد يوصل إلى 520 حرفًا تقريبًا. النتيجة المتوقعة واحدة من ثلاث: insert يفشل، التوكن يتقص لو قاعدة البيانات أو ORM متساهلة، أو الطلبات ترجع 401 لأن القيمة المخزنة ناقصة. ركز: دي مشكلة افتراضات، مش مشكلة authentication.

علميًا، التوكن لازم يتعامل كـ opaque string. يعني سلسلة سرية تمرّرها كما هي، ولا تفكها، ولا تتوقع طولها، ولا تبني regex ضيق عليها. GitHub نفسه أوضح أن العملاء لا يجب أن يعتمدوا على محتوى JWT الداخلي أو يحاولوا التحقق منه محليًا.

افحص الكود في 10 دقائق

ابدأ بأبسط فحص. دور على regex أو validation بيقيّد ghs_ بعدد حروف ثابت. الأمر ده مناسب لمستودع Node أو Python أو Go، وممكن تشغله من root المشروع:

rg "ghs_\[A-Za-z0-9\]\{36\}|ghs_\[A-Za-z0-9_\-\]\{36,64\}|VARCHAR\(64\)|String\(64\)|max_length=64|length\s*===\s*40" .

لو ظهر لك validation بالشكل ده، البديل مش إنك تزود الرقم إلى 520 وخلاص. أفضل طريقة إنك تتحقق من وجود prefix عام فقط، وتخلي التخزين يسمح بطول كافي:

function assertGitHubInstallationToken(token: string) {
  if (!token.startsWith("ghs_")) {
    throw new Error("Expected GitHub installation token prefix");
  }

  if (token.length > 2048) {
    throw new Error("Token is unexpectedly large");
  }

  return token;
}

هنا بنقبل تغير الصيغة، لكن بنحط حد دفاعي كبير ضد مدخلات غريبة. الـ trade-off هنا إنك تفقد validation ضيق كان شكله مطمئن، مقابل إن التطبيق يبقى متوافق مع تغييرات GitHub القادمة.

عدّل التخزين قبل rollout

لو عندك PostgreSQL، استخدم TEXT بدل VARCHAR(64) لتوكنات الوصول. الفرق العملي في PostgreSQL مش كبير من ناحية التخزين، لكنك بتزيل قيد غير مفيد. مثال migration بسيط:

BEGIN;

ALTER TABLE integrations
  ALTER COLUMN github_installation_token TYPE TEXT;

ALTER TABLE integrations
  ADD CONSTRAINT github_installation_token_reasonable_length
  CHECK (github_installation_token IS NULL OR length(github_installation_token) <= 2048);

COMMIT;

لو عندك MySQL، استخدم TEXT أو VARCHAR(2048) حسب نمط الفهارس عندك. لا تعمل index مباشر على التوكن نفسه. لو محتاج lookup، خزّن hash منفصل مثل SHA-256 وابحث به. الافتراض إنك لا تحتاج مقارنة التوكن الخام في queries عادية.

سيناريو واقعي: شركة عندها GitHub App داخلي يثبت على 300 repository ويولد installation token كل ساعة. لو 2% من عمليات التجديد بدأت تفشل بسبب column قصيرة، هتشوف 6 repos تقريبًا في كل دورة بدون checks أو sync. ده كفاية يوقف merge pipeline لفريق كامل.

اختبار سريع قبل الإنتاج

اعمل test بتوكن وهمي بنفس الشكل المتوقع. لا تحتاج توكن حقيقي. المطلوب إنك تختبر التخزين، النقل بين الخدمات، logging، والـ validation:

TOKEN="ghs_123456_$(python - <<'PY'
print('a' * 500)
PY
)"

node -e "const t=process.env.TOKEN; console.log(t.startsWith('ghs_'), t.length)" 

بعدها مرر القيمة في مسار staging: API request، job queue، database write، ثم read. القياس المطلوب بسيط: طول التوكن بعد القراءة لازم يساوي طول التوكن قبل التخزين. لو دخل 511 وخرج 64، عندك قص في مكان ما.

ما الذي سيتغير وماذا لن يتغير

• التغيير يبدأ تدريجيًا من 27 أبريل إلى منتصف مايو 2026 لتوكنات GitHub Actions وبعض التكاملات الأولى.
• من منتصف مايو إلى أواخر يونيو 2026 يبدأ التوسع على كل GitHub App installation tokens.
• توكنات GitHub Enterprise Server ليست ضمن نطاق التغيير الحالي حسب إعلان GitHub.
• التوكنات الموجودة حاليًا ستظل تعمل حتى انتهاء صلاحيتها.
• توكن installation access token عادةً ينتهي بعد ساعة حسب وثائق GitHub.

الطريقة الشائعة الغلط هنا هي محاولة parse للـ JWT الداخلي أو الاعتماد على claims بداخله. ده بيخلق coupling مع تفاصيل GitHub الداخلية. استخدم GitHub API للتحقق من الصلاحيات والنتائج بدل ما تبني منطق أمني على شكل التوكن.

متى لا تستخدم هذه الطريقة

لا تحتاج migration كبير لو أنت تستخدم Octokit SDK فقط ولا تخزّن التوكن ولا تعمل regex عليه ولا تمرره عبر systems بحد طول صغير. كمان لو كل بيئتك GitHub Enterprise Server فقط، فالإعلان الحالي لا يطبق عليها. لكن حتى هنا، فحص rg يستحق 10 دقائق لأنه يكشف ديون تقنية قديمة.

لا تستخدم TEXT بدون حد منطقي لو عندك API عام يستقبل التوكن من مستخدم. في الحالة دي حط حد مثل 2048 حرفًا، وسجّل الطول فقط في logs وليس التوكن نفسه. المكسب أمان وتشخيص أفضل. التكلفة إنك تضيف validation واضح وتحدّث tests.

مصادر

• GitHub Changelog: Notice about upcoming new format for GitHub App installation tokens
• GitHub Docs: Generating an installation access token for a GitHub App
• GitHub Docs: About authentication to GitHub

الخطوة التالية

افتح مستودع التكامل مع GitHub وشغّل أمر rg الموجود فوق. لو لقيت VARCHAR(64) أو regex ثابت، عدّلها اليوم قبل بداية rollout في 27 أبريل 2026.