متغيرات البيئة والأسرار

لماذا يهم

تُنتج أخطاء الإعداد بعضاً من أكثر نتائج خط الأنابيب تضليلاً. فمتغير مفقود يرجع إلى قيمة افتراضية قد يرسل اختبارات طلبات الدمج إلى الإنتاج؛ وعنوان أساسي خاطئ يجعل التشغيل الأخضر لا يثبت شيئاً عن النسخة المختبَرة؛ وكلمة مرور جرى تدويرها تحوّل المجموعة كلها إلى الأحمر بين ليلة وضحاها، فيسجّل أحدهم عشرين عيباً في المنتج هي في الحقيقة تغيير إعداد واحد.

وتضيف الأسرار كلفة أمنية. فالرمز الذي يُودَع في المستودع، أو يُطبع في سطر تصحيح، أو يُلتقط في ملف تتبع مرفوع، يستطيع نسخه كل من يقرأ المستودع أو يفتح التشغيل؛ وكثيراً ما تصل حسابات الاختبار في البيئات المشتركة إلى أنظمة حقيقية: بيئات الدفع التجريبية ومزوّدي البريد الإلكتروني والحسابات السحابية. لهذا تخصّص ورقة OWASP المختصرة لإدارة الأسرار (Secrets Management Cheat Sheet) قسماً مستقلاً لخطوط CI/CD. والمختبِرون يكتبون هذه المهام ويشغّلونها، فهم جزء من خط الدفاع.

تذكير: الإعدادات تعيش خارج شيفرة الاختبار

وضع دليل اختبار CI/CD القواعد الأساسية: تعمل اختبارات خط الأنابيب (Pipeline) في بيئات مؤقتة حيثما أمكن، وفي بيئات مشتركة مثل staging حيث تتطلب الواقعية ذلك؛ وينشئ خط الأنابيب بيانات الاختبار بنفسه؛ وتُحفظ الأسرار في مخزن الأسرار في منصة CI أو في خزنة خارجية، محصورةً في البيئات التي تحتاجها، ومحجوبةً في السجلات، ومدوَّرةً دورياً، ولا تكون أبداً في المستودع، ولا تُطبع، ولا تدخل المخرجات (artifacts). ولا تتلقى مسارات العمل التي تطلقها طلبات الدمج من المستودعات المتفرعة (forks) أسرار المستودع افتراضياً. ويتعمق هذا الدرس خطوة أخرى: كيف تنتقل القيمة من المنصة إلى اختبار قيد التشغيل، وكيف يبقى هذا المسار صحيحاً وآمناً.

كل ما يختلف بين تشغيل وآخر أو بين هدف وآخر هو إعدادات (configuration): العنوان المختبَر، وحساب الاختبار، ومهل الانتظار، والمتصفح، والاختبارات المطلوب تشغيلها. وهذه تبقى خارج شيفرة الاختبار. تسمّي منهجية The Twelve-Factor App ذلك الفصل الصارم بين الإعدادات والشيفرة، وتقترح اختباراً سريعاً: هل يمكن جعل المستودع عاماً الآن دون كشف أي بيانات اعتماد؟ إن كان الجواب لا، فهناك شيء مكانه مخزن الأسرار يقبع في الشيفرة.

• متغيرات الإعداد (configuration variables): إعدادات غير حساسة مثل BASE_URL وTEST_ENV وBROWSER. يجوز أن تُقرأ وتُراجَع وتُطبع.
• الأسرار: قيم تمنح صلاحية وصول، مثل كلمة مرور حساب اختبار أو مفتاح API أو كلمة مرور قاعدة بيانات. تُخزَّن مشفّرة، وتُحجب في السجلات، ولا تُعطى إلا للمهام التي تحتاجها.
• متغيرات المنصة: قيم تضبطها منصة CI في كل تشغيل، مثل CI=true، والإيداع (GITHUB_SHA في GitHub Actions وCI_COMMIT_SHA في GitLab)، ومعرّف التشغيل (GITHUB_RUN_ID وCI_PIPELINE_ID). أثبتها في التقارير لتشير كل نتيجة إلى النسخة والتشغيل بالضبط.

متغيرات البيئة: كيف يقرأ الاختبار إعداداته

متغير البيئة زوج من اسم وقيمة يمرّره نظام التشغيل إلى العملية عند بدئها، وترثه العمليات الفرعية. يضبط مشغّل CI المتغيرات لكل خطوة، ويرثها مشغّل الاختبارات، وتقرؤها شيفرة الاختبار: process.env.BASE_URL في JavaScript وTypeScript، وos.environ["BASE_URL"] في Python، وSystem.getenv("BASE_URL") في Java.

يمكن ضبط القيم على عدة مستويات. في GitHub Actions يعمل المفتاح env على مستوى مسار العمل والمهمة (job) والخطوة (step)، والأكثر تحديداً هو الذي يغلب: قيمة الخطوة تتقدم على قيمة المهمة. ومتغيرات الإعداد المحفوظة في إعدادات المنصة (السياق vars) توجد على مستوى المؤسسة والمستودع والبيئة؛ وقيمة البيئة تغلب قيمة المستودع، وقيمة المستودع تغلب قيمة المؤسسة. ويقدّم GitLab الفكرة نفسها بمتغيرات CI/CD في إعدادات المشروع أو المجموعة. وحين يتلقى اختبار قيمة غير متوقعة، حدّد المستوى الذي جاءت منه قبل أن تشك في المنتج.

• كل قيمة نصّ. فالمتغير HEADLESS=false يصل بوصفه النص "false"، وهو قيمة truthy في JavaScript؛ قارن بالنص، وحوّل الأرقام بـNumber().
• في JavaScript تكون قيمة المتغير المفقود ببساطة undefined، لا خطأً: فيستدعي الاختبار undefined/login، أو ما هو أسوأ: عنواناً احتياطياً.
• القيم الافتراضية مقبولة للإعدادات التي لا ضرر منها مثل مهلة الانتظار، ولا تُقبل أبداً للهدف أو لبيانات الاعتماد. فغياب BASE_URL يجب أن يوقف التشغيل، لا أن يرجع إلى الإنتاج.
• المتغيرات لا تُحجب. تنبّه وثائق GitHub إلى أن المتغيرات تظهر دون حجب في مخرجات البناء، فكلمة المرور المحفوظة متغيراً تُطبع كما هي.

// tests/config.ts: read once, check early, never print a secret
const required = ['TEST_ENV', 'BASE_URL', 'TEST_USER', 'TEST_PASSWORD'];
const missing = required.filter((name) => !process.env[name]);
if (missing.length > 0) {
  throw new Error('Missing variables: ' + missing.join(', ')); // no silent fallback
}

export const config = {
  env: process.env.TEST_ENV!,                        // staging | production
  baseUrl: process.env.BASE_URL!,
  user: process.env.TEST_USER!,
  password: process.env.TEST_PASSWORD!,             // a secret: use it, never log it
  headless: process.env.HEADLESS !== 'false',        // every value is a string
  timeoutMs: Number(process.env.TIMEOUT_MS ?? '30000'), // harmless default
  allowWrites: process.env.TEST_ENV !== 'production',
};

console.log('env=' + config.env + ' baseUrl=' + config.baseUrl); // never the password

الأسرار: التخزين والحجب ومبدأ أقل الصلاحيات

يُخزَّن السر مرة واحدة، في مخزن الأسرار في منصة CI أو في خزنة خارجية، ويُحقن في المهمة وقت التشغيل، غالباً بوصفه متغير بيئة. لا يعرض GitHub السر المحفوظ مرة أخرى أبداً؛ يمكنك استبداله فقط. ويوفر GitLab ذلك مع الخيار «Masked and hidden». والأسرار لا تدخل المستودع أبداً: لا في ملف خط الأنابيب، ولا في ملف .env مُودَع، ولا في ملف بيانات اختبار، ولا في بيئة Postman مُصدَّرة، ولا في لقطة شاشة داخل تقرير عيب. وعلى جهازك احفظها في ملف .env يستبعده .gitignore. والسر الذي وصل إلى تاريخ Git يُعدّ مسرَّباً حتى لو حذفه الإيداع التالي، لأن التاريخ يحتفظ بكل نسخة: ألغِه ودوّره أولاً، ثم نظّف.

الحجب (Masking) يستبدل القيمة الدقيقة للسر في سجل المهمة بـ*** (في GitHub) أو [MASKED] (في GitLab). إنه شبكة أمان فيها ثغرات، وكلتا المنصتين تقول إنه غير مضمون. وتطلب وثائق GitHub أن تسجّل سراً أيضاً كل قيمة محوَّلة (بترميز Base64 أو ترميز URL) وكل قيمة مشتقة، مثل رمز موقَّع بمفتاح سري، باستخدام أمر مسار العمل ::add-mask::، وتحذّر من أن السر الموضوع داخل كتلة JSON أو YAML أقل احتمالاً بكثير أن يُحجب. والحجب لا يغطي إلا السجل: ملفات التتبع (traces) وملفات HAR ولقطات الشاشة ومقاطع الفيديو وتقارير HTML التي التقطت ترويسة Authorization أو كلمة مرور مكتوبة تُرفع كما هي.

• بيانات اعتماد اختبار مخصّصة لكل بيئة، بأدنى دور تحتاجه الاختبارات: لا حساب شخص بعينه أبداً، ولا حساب مسؤول «من باب الاحتياط».
• احصر كل سر في البيئة التي تحتاجه. في GitHub Actions لا يصل سر البيئة إلا إلى المهام التي تشير إلى تلك البيئة، ومع المراجعين المطلوبين (required reviewers) لا تستطيع المهمة قراءته قبل أن يوافق أحدهم؛ ولا تصل المتغيرات المحمية (protected) في GitLab إلا إلى خطوط الأنابيب على الفروع أو الوسوم المحمية.
• امنح رمز خط الأنابيب نفسه صلاحية القراءة فقط افتراضياً (permissions: contents: read للرمز GITHUB_TOKEN)، ووسّعها فقط في المهمة التي تحتاج إلى أكثر.
• أبقِ على قاعدة المستودعات المتفرعة: مسارات العمل التي تطلقها طلبات الدمج من forks لا تتلقى أسرار المستودع. شغّل الاختبارات المعتمدة على الأسرار بعد الدمج بدلاً من الالتفاف على القاعدة.
• فضّل بيانات الاعتماد قصيرة العمر على المفاتيح طويلة العمر: مع OpenID Connect (OIDC) تقدّم المهمة إلى المزوّد السحابي رمزاً تصدره منصة CI، فتتلقى بيانات اعتماد قصيرة العمر لذلك التشغيل، ولا يُخزَّن أي مفتاح سحابي سراً. ودوّر الباقي وفق جدول وفوراً بعد أي انكشاف، واحذف ما لا تستخدمه أي مهمة.

جرّبها: مولّد الأسرار العشوائية جرّبها: مرمّز Base64 جرّبها: مختبِر مصادقة API

إعدادات كل بيئة: مجموعة واحدة وأهداف متعددة

ينبغي أن تعمل المجموعة نفسها على بيئة مؤقتة لطلب الدمج وعلى staging وعلى الإنتاج دون أي تغيير في الشيفرة: الإعدادات وحدها هي التي تختلف. اتفق مع الفريق، كتابةً، على ما يتغير بين البيئات وما يجب ألا يتغير. تبقى شيفرة الاختبار والنسخة المختبَرة كما هي؛ ومن الممارسات الشائعة أن تُبنى النسخة مرة واحدة ثم تُرقّى هي نفسها عبر البيئات، فيقول النجاح على staging شيئاً عن النسخة التي تصل إلى الإنتاج.

تحمل آليتان هذه الفروق. الإعدادات غير السرية يمكن أن تكون في ملف مُودَع ومراجَع لكل بيئة (config/staging.json) أو في متغيرات على مستوى البيئة؛ أما الأسرار فلا تأتي إلا من المخزن، محصورةً في كل بيئة. في GitHub Actions توجد البيئات (environments) بمتغيراتها وأسرارها وقواعد حمايتها؛ وفي GitLab يمكن إعطاء متغير المشروع نطاق بيئة (environment scope)، أما حصر متغيرات المجموعة في بيئة فيتطلب فئة مدفوعة. وللإنتاج قواعده الخاصة: مجموعة دخان صغيرة للقراءة فقط، وحساب مراقبة مخصّص، وحارس في المجموعة يرفض تشغيل الاختبارات التي تغيّر البيانات هناك.

Setting           PR run (ephemeral)    staging                 production
----------------  --------------------  ----------------------  ----------------------
BASE_URL          localhost:3000        staging.shop.example    shop.example
Test account      seeded per run        qa-buyer (staging)      smoke-monitor (read)
Payments          mocked                provider sandbox        not exercised
Tests that run    @pr subset            full regression         @smoke only
Writes data       yes, reset per run    yes, own records        no
Secrets from      none needed           staging environment     production environment
Approval          none                  none                    required reviewer

جرّبها: مقارنة النصوص (Diff)

مثال تطبيقي: اختبارات staging وفحص دخان على الإنتاج

متجر إلكتروني ينشر من الفرع main. يريد الفريق تشغيل مجموعة الاختبارات الشاملة (end-to-end) كاملةً على staging بعد كل دمج، ثم مجموعة دخان فرعية بحساب للقراءة فقط بعد وصول الإصدار إلى الإنتاج. يعرض المقتطف أدناه مهام الاختبار؛ وقد حُذفت مهام البناء والنشر.

• الأسماء نفسها والقيم مختلفة: vars.BASE_URL وsecrets.TEST_PASSWORD تأخذان قيمة staging أو قيمة الإنتاج بحسب environment الخاصة بالمهمة، لأن القيمة على مستوى البيئة تتقدم على قيمة المستودع التي تحمل الاسم نفسه. وشيفرة الاختبار لا تتغير.
• يعمل مسار العمل عند الدفع (push) إلى main فقط؛ أما طلبات الدمج فتستخدم الإعداد المؤقت من الجدول السابق ولا تحتاج إلى أسرار البيئات المشتركة.
• السطر permissions: contents: read يجعل GITHUB_TOKEN للقراءة فقط في المهمتين.
• تنتظر مهمة الإنتاج موافقة مراجع مطلوب (تُضبط على البيئة في إعدادات المستودع)، وعندها فقط تستطيع قراءة أسرار الإنتاج؛ ثم تشغّل اختبارات @smoke بحساب للقراءة فقط، وتكون قيمة allowWrites في الإعدادات false.
• في السجل تعرض مجموعة Run npx playwright test قيم env الخاصة بالخطوة: BASE_URL واضحاً، وTEST_PASSWORD بالشكل ***. ثم تطبع الاختبارات السطر env=staging baseUrl=https://staging.shop.example. وعندما يفشل تشغيل، تخبرك هذه الأسطر بما اختُبر فعلاً، وعليها يبني الدرس التالي.

# .github/workflows/e2e.yml (excerpt; build and deploy jobs omitted)
on:
  push:
    branches: [main]
permissions:
  contents: read                       # GITHUB_TOKEN can only read the code
jobs:
  e2e-staging:
    runs-on: ubuntu-latest
    environment: staging               # staging variables and secrets only
    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test
        env:
          TEST_ENV: staging
          BASE_URL: ${{ vars.BASE_URL }}                # variable: shown in logs
          TEST_USER: ${{ vars.TEST_USER }}
          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}   # secret: masked in logs
  smoke-production:
    needs: e2e-staging                 # full file: after the production deploy job
    runs-on: ubuntu-latest
    environment: production            # waits for a required reviewer
    steps:
      - uses: actions/checkout@v7
      - run: npm ci
      - run: npx playwright install --with-deps
      - run: npx playwright test --grep @smoke
        env:
          TEST_ENV: production
          BASE_URL: ${{ vars.BASE_URL }}
          TEST_USER: ${{ vars.TEST_USER }}
          TEST_PASSWORD: ${{ secrets.TEST_PASSWORD }}

جرّبها: منسّق YAML

أسئلة شائعة

المراجع

• OWASP Cheat Sheet Series: Secrets ManagementOWASP Foundationكيف تُولَّد مفاتيح API والأسرار وتُخزَّن وتُدوَّر وتُبقى بعيدة عن الشيفرة والسجلات.
• Using secrets in GitHub ActionsGitHubتخزين بيانات الاعتماد كأسرار على مستوى المستودع أو البيئة أو المؤسسة، وكيف يخفيها GitHub في السجلات، ولماذا لا تُمرَّر إلى مسارات العمل التي تُطلقها النسخ المتفرعة (forks).
• GitHub Actions documentationGitHubكيف تُعرَّف مسارات العمل والمهام والمشغّلات والمخرجات في GitHub Actions — حيث تعمل الاختبارات الآلية عند كل دفع أو طلب دمج.
• GitLab CI/CDGitLabكيف تُعرَّف خطوط الأنابيب والمهام والمخرجات — حيث تعمل حزمة الانحدار الآلية عند كل تغيير.