CICDSample

افزودن CI/CD به یک کتابخانهٔ Net.

نویسندگان: احمد سلیمی - آرمان زارعی - مبینا پورنعمت

---

1. CI/CD چیست و چرا اهمیت دارد:

   از طریق لینک‌های زیر، می‌توانید درمورد مفهوم CI/CD و اهمیت آن مطالعه کنید.

   • What is CI/CD?
   • What’s the Point of CI Anyway?
   • The Journey to CI/CD

2. آشنایی با GitHub Actions و اضافه کردن CI/CD Pipeline به ریپازیتوری:

   یکی از ابزار CI/CD معروف، GitHub Actions است که به کمک آن، می‌توانیم یک Pipeline شامل عملیات build، اجرای unit test ها و همچنین انتشار package و دیگر عملیاتی که در دستهٔ CI/CD می‌گنجد را به ریپازیتوری گیت‌هاب خود اضافه کنیم.

   این کار، برر روی یک کتابخانهٔ آزمایشی که به زبان #C نوشته شده است و در این ریپازیتوری موجود است انجام شده است و می‌توانید کدها و تنظیمات مربوطه را در این ریپازیتوری ببینید. مراحل افزودن CI/CD بصورت زیر می‌باشد.

   1. فایلی در مسیر زیر در ریپازیتوری خود می‌سازیم:

      .github/workflows/buildPipeline.yml
      

   2. برای pipeline خود یک نام تعریف می‌کنیم: (به فایل buildPipeline.yml اضافه کنید.)

      name: build

   3. مشخص می‌کنیم که pipeline در هنگام push و pull request روی master اجرا شود.

      on:
        push:
          branches: [ master ]
        pull_request:
          branches: [ master ]

   4. مراحل Pipeline را به ترتیب تعریف می‌کنیم. در ابتدا مشخص می‌کنیم که pipeline روی آخرین ورژن ubuntu اجرا شود: (می‌توان آن را تغییر داد)

      jobs:
        build:
          runs-on: ubuntu-latest

   5. در این مرحله مشخص می‌کنیم که CI از agent ای به نام actions/checkout@v2 استفاده کند: (برای مطالعه بیشتر این لینک را بخوانید.)

          steps:
          - uses: actions/checkout@v2

   6. در این مرحله مشخص می‌کنیم که .Net core 3.1 نصب شود.

          - name: Setup .NET Core
            uses: actions/setup-dotnet@v1
            with:
              dotnet-version: 3.1.301

   7. سپس dependency های پروژه restore شوند:‌ (دقت کنید که به جای <path to solution> آدرس فولدر solution خود را مشخص کنید.)

          - name: Install dependencies
            run: dotnet restore
            working-directory: <path to solution>

   8. solution را build می‌کنیم.

          - name: Build
            run: dotnet build --configuration Release --no-restore
            working-directory: <path to solution>

   9. تست‌ها را run می‌کنیم.

          - name: Test
            run: dotnet test --no-restore --verbosity normal --collect:"XPlat Code Coverage"
            working-directory: <path to solution>

      تبریک! CI شما آماده‌است. فایل را commit کرده و روی master پوش کنید.

      در ریپازیتوری خود وارد منوی Actions شوید؛ همانطور که مشاهده می‌کنید، Pipeline شما در حال اجرا است:

      

      با ورود به بخش build با تصویر زیر مواجه می‌شوید که پیشرفت CI را نشان می‌دهد:

      

   10. افزودن badge وضعیت CI به README:

       از این قسمت دکمهٔ Copy status badge Markdown را انتخاب کرده و متن کپی‌شده را به README ریپازیتوری خود اضافه کنید.

       

       می‌توانید وضعیت Pipeline را در هر لحظه مشاهده کنید:

       

   11. افزودن مشاهده وضعیت code coverage:

       با اکانت GitHub خود در سایت codecov.io وارد شوید. سپس به این آدرس بروید:

       https://codecov.io/gh/<github-username>/<repo-name>
       

       

       توکن Codecov خود را کپی کرده، در Secretهای ریپازیتوری خود با نام CODECOV_TOKEN اضافه کنید.

   12. بخش زیر را به فایل buildPipeline.yml اضافه کنید:

           - name: Publish code coverage reports to codecove.io
             uses: codecov/codecov-action@v1
             with:
               token: ${{ secrets.CODECOV_TOKEN }}
               files: ./**/coverage.cobertura.xml
               fail_ci_if_error: true

   13. مارکدان زیر را به Readme ریپازیتوری خود اضافه کنید تا Badge مربوط به Code Coverage نیز نمایش داده شود. ( جای github-username و repo-name اطلاعات خود را وارد کنید. )

       [![codecov](https://codecov.io/gh/<github-username>/<repo-name>/branch/master/graph/badge.svg)](https://codecov.io/gh/<github-username>/<repo-name>)

       اکنون مشاهده خواهید کرد که در هر لحظه، وضعیت code coverage شما نیز نمایش داده می‌شود:

       

       تا به اینجای کار، کل فایل buildPipeline.yml باید بصورت زیر باشد:

       name: build
       
       on:
         push:
           branches: [ master ]
         pull_request:
           branches: [ master ]
       
       jobs:
         build:
           runs-on: ubuntu-latest
       
           steps:
           - uses: actions/checkout@v2
       
           - name: Setup .NET Core
             uses: actions/setup-dotnet@v1
             with:
               dotnet-version: 3.1.301
           
           - name: Install dependencies
             run: dotnet restore
             working-directory: <path to solution>
       
           - name: Build
             run: dotnet build --configuration Release --no-restore
             working-directory: <path to solution>
       
           - name: Test
             run: dotnet test --no-restore --verbosity normal --collect:"XPlat Code Coverage"
             working-directory: <path to solution>
       
           - name: Publish code coverage reports to codecove.io
             uses: codecov/codecov-action@v1
             with:
               token: ${{ secrets.CODECOV_TOKEN }}
               files: ./**/coverage.cobertura.xml
               fail_ci_if_error: true

   14. انتشار package در NuGet.org:

       NuGet، پکیج منیجر معروف مایکروسافت برای انتشار پکیج‌های Net. است. برای کسب اطلاعات بیشتر، این لینک را مطالعه کنید. در این مرحله، می‌خواهیم یک Pipeline جدید بسازیم که هنگام release یک ورژن در ریپازیتوری، پکیج را در NuGet.org منتشر کند. پیش از شروع، اکانت خود را در سایت NuGet.org ساخته و Token مربوط به اکانت خود را در Secret های ریپازیتوری با نام NUGET_API_KEY ذخیره کنید.

       ابتدا باید مشخصات package را در فایل csproj. مربوط به پروژهٔ خود مشخص کنید. بدین منظور، این فایل باید به صورت زیر باشد:

       <Project Sdk="Microsoft.NET.Sdk">
       
           <PropertyGroup>
               <TargetFramework>netstandard2.0</TargetFramework>
               <PackageId>[LibraryName]</PackageId>
               <Authors>[TeamMembers]</Authors>
               <Company>[Company Name]</Company>
           </PropertyGroup>
       
       </Project>

       در ادامه، برای ساخت Pipline مربوط به publish، فایل زیر را می‌سازیم:

       .github/workflows/publishPipeline.yml
       

       سپس مراحل زیر را به آن اضافه می‌کنیم:

       • نام، trigger و OS مربوط به pipeline را مشخص می‌کنیم.

       name: publish
       
       on:
         release:
           types:
             published
       
       jobs:
         publish:
           runs-on: ubuntu-latest
       

       • نصب .Net Core:

           steps:
           - uses: actions/checkout@v2
       
           - name: Setup .NET Core
             uses: actions/setup-dotnet@v1
             with:
               dotnet-version: 3.1.301

       • گرفتن ورژن release کنونی. توجه کنید که تگ release بعنوان ورژن به NuGet داده می‌شود. در نتیجه، الگوهای قابل قبول ورژن را از اینجا بخوانید و تگ را مطابق این الگو بزنید.

           - name: Get current release version
             id: version
             uses: pozetroninc/github-action-get-latest-release@master
             with:
               repository: <github-username>/<repo-name>

       • build و ساخت پکیج NuGet (به جای <path to classlib project> آدرس فولدری را که فایل csproj. مربوط به پروژه class library در آن قرار دارد بنویسید.)

           - name: Build library and generate NuGet Package
             run: dotnet pack -c Release -o artifacts -p:PackageVersion=${{ steps.version.outputs.release }}
             working-directory: <path to classlib project>

       • انتشار پکیج NuGet

           - name: Publish NuGet Package
             run: dotnet nuget push ./**/*.nupkg -k ${{ secrets.NUGET_API_KEY }} -s https://api.nuget.org/v3/index.json

       از این پس، هر گاه در ریپازیتوری خود تگ بزنید، Pipeline فوق trigger می‌شود و در نتیجه پکیج شما push می‌شود. همچنین در منوی Actions می‌توانید وضعیت publish را مشاهده کنید. پکیج منتشر شدهٔ خود را نیز می‌توانید در آدرس زیر مشاهده کنید:

       nuget.org/packages/[PackageId]
       

       

   همانطور که در ابتدا نیز گفته شد، نمونه فایل‌های pipeline ها و یک پروژه class library و xunit نمونه، در این ریپازیتوری موجود می‌باشد.

   از این پس، می‌توانید در هر پروژه دیگری، از این پکیج استفاده کنید. با استفاده از دستور زیر، می‌توانید پکیج خود را به هر پروژه‌ای اضافه کنید.

   dotnet add package [packageId]
   

   با این command، پکیج به پروژه شما اضافه می‌شود و می‌توانید از کلاس‌های آن استفاده کنید. همچنین اگر پکیج خود را update کرده باشید، با اجرای این command، نسخه جدید پکیج به پروژه شما اضافه می‌شود. (نمونهٔ اضافه کردن پکیج به پروژه را می‌توانید در پوشهٔ ConsoleSample از ریپازیتوری مذکور مشاهده کنید.)