مزامنة مستودع GitHub مع تكوين التطبيق

يمكن للفرق التي ترغب في الاستمرار في استخدام ممارسات التحكم بالمصادر الحالية استخدام GitHub Actions لمزامنة مستودع GitHub الخاص بها تلقائيًا مع مخزن تكوين التطبيق الخاص بها. يسمح لك هذا بإجراء تغييرات على ملفات التكوين الخاصة بك كما تفعل عادة، أثناء الحصول على مزايا تكوين التطبيق مثل:
    • تكوين مركزي خارج التعليمات البرمجية الخاصة بك
    • تحديث التكوين دون إعادة نشر التطبيق بأكمله
    • التكامل مع خدمات مثل Azure App Service و Azure Functions.

يحدد سير عمل GitHub Actions عملية تلقائية في مستودع GitHub. يقوم إجراء مزامنة تكوين التطبيق من Azure بتشغيل التحديثات إلى مثيل تكوين التطبيق عند إجراء تغييرات على مستودع المصدر. يستخدم ملف YAML (.yml) الموجود في مسار /.github/workflows/ للمستودع الخاص بك لتحديد الخطوات والمعلمات. يمكنك تشغيل تحديثات التكوين عند دفع ملفات تكوين التطبيق أو مراجعتها أو تفريعها تمامًا كما تفعل مع التعليمات البرمجية للتطبيق.

توفر وثائق GitHub عرضًا متعمقًا لسير عمل GitHub وإجراءاته.

تمكين GitHub Actions في المستودع الخاص بك

لبدء استخدام GitHub Actions هذا، انتقل إلى المستودع وحدد علامة التبويب Actions. حدد New workflow، ثم قم بإعداد سير عمل بنفسك. وأخيرًا، ابحث في السوق عن "مزامنة تكوين التطبيق من Azure."

مزامنة ملفات التكوين بعد دفعة

يقوم هذا الإجراء بمزامنة ملفات تكوين التطبيق من Azure عند دفع تغيير إلى appsettings.json. عندما يدفع أحد المطورين تغييرًا إلى appsettings.json، يقوم إجراء مزامنة تكوين التطبيق بتحديث مثيل تكوين التطبيق بالقيم الجديدة.

يحدد القسم الأول من سير العمل هذا أن الإجراء يتم تشغيله علىدفعة تحتوي على appsettings.jsonالفرع الرئيس. يسرد القسم الثاني المهام التي يتم تشغيلها بمجرد تشغيل الإجراء. يتحقق الإجراء من الملفات ذات الصلة ويحدث مثيل تكوين التطبيق باستخدام سلسلة الاتصال المخزنة كبيانات سرية في المستودع. لمزيد من المعلومات حول استخدام البيانات السرية في GitHub، راجع مقالة GitHub حول إنشاء واستخدام البيانات السرية المشفرة.

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your                        
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }} 
          separator: ':' 

استخدام مزامنة مقيدة

بشكل افتراضي، لا يقوم GitHub Action بتمكين الوضع المقيد، ما يعني أن المزامنة ستضيف فقط قيم المفاتيح من ملف التكوين إلى مثيل تكوين التطبيق (لن يتم حذف أزواج قيم المفاتيح). سيؤدي تمكين الوضع المقيد إلى حذف أزواج قيم المفاتيح غير الموجودة في ملف التكوين من مثيل تكوين التطبيق، حتى يتطابق مع ملف التكوين. إذا كنت تقوم بالمزامنة من مصادر متعددة أو تستخدم Azure Key Vault مع تكوين التطبيق، فسترغب في استخدام بادئات أو تسميات مختلفة مع مزامنة مقيدة لتجنب مسح إعدادات التكوين من ملفات أخرى (راجع العينات أدناه).

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your 
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }}  
          separator: ':' 
          label: 'Label' 
          prefix: 'Prefix:' 
          strict: true 

مزامنة ملفات متعددة في إجراء واحد

إذا كان التكوين الخاص بك في ملفات متعددة، فيمكنك استخدام النمط أدناه لتشغيل مزامنة عند تعديل أي ملف. يستخدم هذا النمط مكتبة glob https://www.npmjs.com/package/glob. لاحظ أنه إذا كان اسم ملف التكوين يحتوي على فاصلة، فيمكنك استخدام شرطة مائلة للخلف لتجنب الفاصلة.

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'
      - 'appsettings2.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: '{appsettings.json,appsettings2.json}'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'

المزامنة حسب البادئة أو التسمية

سيؤدي تحديد البادئات أو التسميات في إجراء المزامنة إلى مزامنة تلك المجموعة المعينة فحسب. يعد هذا أمرًا مهما لاستخدام المزامنة المقيدة مع ملفات متعددة. اعتمادًا على كيفية إعداد التكوين، يمكن إقران بادئة أو تسمية بكل ملف ثم يمكن مزامنة كل بادئة أو تسمية بشكل منفصل بحيث لا يتم استبدال أي شيء. عادةً ما يتم استخدام البادئات لتطبيقات أو خدمات مختلفة ويتم استخدام التسميات لبيئات مختلفة.

المزامنة حسب البادئة:

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'appsettings.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          prefix: 'Prefix::'

المزامنة حسب التسمية:

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'appsettings.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          label: 'Label'

استخدام تسمية ديناميكية عند المزامنة

يدرج الإجراء التالي تسمية ديناميكية في كل مزامنة، مما يضمن إمكانية تحديد كل مزامنة بشكل فريد والسماح بتعيين تغييرات التعليمات البرمجية إلى تغييرات التكوين.

يحدد القسم الأول من سير العمل هذا أن الإجراء يتم تشغيله علىدفعة تحتوي على appsettings.jsonالفرع الرئيس. يقوم القسم الثاني بتشغيل مهمة تنشئ تسمية فريدة لتحديث التكوين استنادًا إلى تجزئة التثبيت. تقوم المهمة بعد ذلك بتحديث مثيل تكوين التطبيق بالقيم الجديدة والتسمية الفريدة لهذا التحديث.

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # Creates a label based on the branch name and the first 8 characters          
      # of the commit hash 
      - id: determine_label 
        run: echo ::set-output name=LABEL::"${GITHUB_REF#refs/*/}/${GITHUB_SHA:0:8}" 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your 
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }}  
          separator: ':' 
          label: ${{ steps.determine_label.outputs.LABEL }} 

استخدام Azure Key Vault مع GitHub Action

يجب على المطورين الذين يستخدمون Azure Key Vault مع AppConfiguration استخدام ملفين منفصلين، عادة ما يكون appsettings.json وsecretreferences.json. سيحتوي secretreferences.json على عنوان URL لبيانات سرية لمفتاح المخزن.

{ "mySecret": "{"uri":"https://myKeyVault.vault.azure.net/secrets/mySecret"}" }

يمكن بعد ذلك تكوين GitHub Action لإجراء مزامنة مقيدة على appsettings.json، متبوعة بمزامنة غير مقيدة على secretreferences.json. سيقوم النموذج التالي بتشغيل مزامنة عند تحديث أي ملف من الملفين:

on:
  push:
    branches:
      - 'main'
    paths:
      - 'appsettings.json'
      - 'secretreferences.json'

jobs:
  syncconfig:
    runs-on: ubuntu-latest
    steps:
      # checkout done so that files in the repo can be read by the sync
      - uses: actions/checkout@v1
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'appsettings.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          strict: true
      - uses: azure/appconfiguration-sync@v1
        with:
          configurationFile: 'secretreferences.json'
          format: 'json'
          # Replace <ConnectionString> with the name of the secret in your repository
          connectionString: ${{ secrets.<ConnectionString> }}
          separator: ':'
          contentType: 'application/vnd.microsoft.appconfig.keyvaultref+json;charset=utf-8'

استخدام الحد الأقصى للعمق للحد من GitHub Action

السلوك الافتراضي لسمات JSON المتداخلة هو تبسيط الكائن بأكمله. يعرف JSON أدناه زوج قيمة المفتاح هذا:

مفتاح	القيمة
Object:Inner:InnerKey	InnerValue

{ "Object": 
    { "Inner":
        {
        "InnerKey": "InnerValue"
        }
    }
}

إذا كان الغرض من الكائن المتداخل هو أن يكون القيمة المدفوعة إلى مثيل التكوين، يمكنك استخدام قيمة العمق لإيقاف التبسيط بالعمق المناسب.

on: 
  push: 
    branches: 
      - 'main' 
    paths: 
      - 'appsettings.json' 
 
jobs: 
  syncconfig: 
    runs-on: ubuntu-latest 
    steps: 
      # checkout done so that files in the repo can be read by the sync 
      - uses: actions/checkout@v1 
      - uses: azure/appconfiguration-sync@v1 
        with: 
          configurationFile: 'appsettings.json' 
          format: 'json' 
          # Replace <ConnectionString> with the name of the secret in your 
          # repository 
          connectionString: ${{ secrets.<ConnectionString> }}  
          separator: ':' 
          depth: 2 

بالنظر إلى العمق 2، يقوم المثال أعلاه الآن بإرجاع زوج قيمة المفتاح التالي:

مفتاح	القيمة
Object:Inner	{"InnerKey":"InnerValue"}

فهم مدخلات الإجراء

تحدد معلمات الإدخال البيانات التي يستخدمها الإجراء أثناء وقت التشغيل. يحتوي الجدول التالي على معلمات الإدخال التي تقبلها مزامنة تكوين التطبيق والقيم المتوقعة لكل منها. لمزيد من المعلومات حول مدخلات الإجراء لـ GitHub Actions، راجع وثائق GitHub.

إشعار

معرفات الإدخال غير حساسة لحالة الأحرف.

اسم الإدخال	مطلوب؟	القيمة‬
ملف التكوين	‏‏نعم‬	المسار النسبي لملف التكوين في المستودع. يتم دعم أنماط Glob ويمكن أن تتضمن ملفات متعددة.
format	‏‏نعم‬	تنسيق الملف الخاص بملف التكوين. التنسيقات الصالحة هي: JSON، YAML، الخصائص.
سلسلة الاتصال	‏‏نعم‬	سلسلة اتصال القراءة والكتابة لمثيل تكوين التطبيق. ينبغي تخزين سلسلة الاتصال كبيانات سرية في مستودع GitHub، وينبغي استخدام الاسم السري في سير العمل فحسب.
الفاصل	‏‏نعم‬	الفاصل المستخدم عند تبسيط ملف التكوين إلى أزواج قيم المفاتيح. القيم الصالحة هي: . , ; : - _ __ /
البادئة	لا	البادئة التي ستضاف إلى بداية المفاتيح.
تسمية	لا	التسمية المستخدمة عند إعداد أزواج قيمة المفتاح. إذا لم يتم تحديدها، يتم استخدام تسمية فارغة.
مقيد	لا	قيمة منطقية تحدد ما إذا كان الوضع المقيد ممكنًا أم لا. القيمة الافتراضية هي false.
العمق	لا	أقصى عمق لتبسيط ملف التكوين. يجب أن يكون العمق رقمًا موجبًا. لن يكون للإعداد الافتراضي قيمة لأقصى عمق.
العلامات	لا	تحديد مجموعة العلامات على أزواج قيم المفاتيح. التنسيق المتوقع هو شكل سلسلة لعنصر JSON بالشكل التالي: { [propertyName: string]: string; } تصبح كل قيمة اسم خاصية علامة.

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

في هذه المقالة، تعرفت على GitHub Action لمزامنة تكوين التطبيق وكيفية استخدامه لأتمتة التحديثات إلى مثيل تكوين التطبيق. لمعرفة كيفية تفاعل تكوين التطبيق من Azure مع التغييرات في أزواج قيم المفاتيح، تابع إلى المقالة التالية.