مقدمه‌ای بر GitHub Actions

اگر بخواهید در توسعه برنامه های متن باز (open source) شرکت کنید یا از پروژه های متن باز زیاد استفاده می کنید احتمالا با عبارت GitHub Actions (به معنی عملیات های گیت هاب) آشنا شده اید. GitHub Actions به شما اجازه می دهند عملیات های خاصی به نام action را به صورت خودکار روی repository خود انجام دهید و به نوعی یک چرخه زندگی (lifecycle) را برایش تعریف کنید. این موضوع در هنگام بهره برداری پیوسته (continuous deployment) و یکپارچه سازی پیوسته (Continuous Integration) به شما کمک می کنند. احتمالا با خواندن این پاراگراف کمی گیج شده باشید بنابراین بگذارید قدم به قدم این موضوع را بررسی کنیم.

سطح مقاله: این مقاله برای افراد مبتدی در نظر گرفته نشده است بلکه برای برنامه نویسانی است که با گیت هاب و سیستم مدیریت نسخه مانند git کار کرده اند. GitHub Actions از مباحث پیچیده تر گیت هاب هستند.

آشنایی با یکپارچه سازی پیوسته و بهره برداری پیوسته

Continuous Integration یا یکپارچه سازی پیوسته که به صورت مخفف CI نیز نامیده می شود به فرآیند خودکارسازی در ادغام کدهای چندین برنامه نویس در یک پروژه گفته می شود. یعنی چه؟ در یکپارچه سازی پیوسته ما سیستمی را پیاده سازی می کنیم که دائما کدهای جدید توسعه دهندگان یک پروژه را تحت نظر دارد و زمانی که یک نفر کد جدیدی را به پروژه اضافه می کند، ابتدا آن کد توسط اسکریپت های تست، بررسی می شود و در صورتی که مشکلی برای برنامه ایجاد نکند به به صورت خودکار به سورس کد برنامه اضافه خواهد شد.

احتمالا بپرسید آیا یکپارچه سازی پیوسته (CI) آنچنان مهم است؟ باید بگویم بله! در پروژه های بزرگ که بیشتر از یک یا دو توسعه دهنده دارد، هر بار که کد جدیدی نوشته می شود توسعه دهندگان باید با هم صحبت کنند و همه چیز را هماهنگ کنند تا کد جدید به سورس نهایی اضافه شود و در عین حال مشکلی در این میان به وجود نیاید. اگر شما پروژه کوچکی را دارید شاید به CI نیازی نداشته باشید اما در پروژه های بزرگ این هماهنگی های لازم آنچنان زیاد می شود که زمان بسیار زیادی را از توسعه دهندگان می گیرد. همچنین علاوه بر زمان تلف شده، احتمال ایجاد خطا و بهم ریختن سورس کد اصلی نیز بسیار بالا است. این طبیعت هر پروژه ای است که چندین توسعه دهنده مختلف دارد.

زمانی که CI در پروژه ما باشد به توسعه دهندگان اجازه می دهد به صورت مستقل و با سرعت خودشان شروع به کار روی ویژگی های مختلف برنامه کنند بدون اینکه نیاز به هماهنگی داشته باشند.

در مرحله بعدی Continuous delivery یا تحویل پیوسته را داریم که قدم بعد از CI محسوب می شود. کار تحویل پیوسته این است که با استفاده از ابزار های درون پروژه مستقیما آن را بسازد تا آماده deploy یا بهره برداری شویم. در واقع در مرحله CI کدهای جدید کاربر به سورس برنامه اضافه می شوند. در مرحله بعدی (تحویل پیوسته) این کدها کامپایل و bundle می شوند تا به صورت محصول نهایی آماده باشند اما فعلا تبدیل به محصول نهایی نمی شوند.

در آخرین مرحله continuous deployment یا بهره برداری پیوسته را داریم که با نام CD نیز مشخص می شود. اگر تمام تست ها در مراحل قبلی بدون مشکل نوشته شوند، در این مرحله کدهای کامپایل شده نهایی شده و به سمت کاربران ارسال می شوند. مثلا اگر یک پکیج را در گیت هاب داشته باشیم، مرحله آخر این است که این پکیج روی NPM یا هر وب سایتی که کاربران از آن استفاده می کنند منتشر شود. در واقع در این مرحله است که استفاده کنندگان از برنامه ما، تغییر را مشاهده می کنند.

گیت هاب actions به شما کمک می کنند تا مفاهیم CI و CD را پیاده سازی کنید!

اهمیت GitHub Actions

قبل از اینکه بخواهیم به بخش های فنی ماجرا بپردازیم باید از خودمان بپرسیم که اهمیت github actions چیست و اصلا چرا توسعه دهندگان باید به آن اهمیت بدهند؟

مدیریت توسط گیت هاب: Github Actions در خود سایت گیت هاب پیاده سازی می شوند بنابراین نیازی به ساخت یک وب سایت یا سرور جداگانه ندارید بلکه گیت هاب خود این کار را به صورت رایگان برایتان انجام می دهد. همچنین با انجام این کار تمام پروژه شما و مسائل مرتبط با آن مانند pull request ها و issues همگی در یک محل قرار خواهند داشت.

تست برنامه های Multi-container: در بسیاری از اوقات توسعه دهندگان مجبور هستند از برنامه های Multi-container استفاده کنند. اگر با داکر آشنا باشید می دانید که container به معنی نگهدارنده است و برنامه ما را در خود دارد. از طرف دیگر برنامه های multi-container برنامه هایی هستند که بخش های مختلف برنامه را در container های مختلفی نگه می دارند به طوری که هر image حاوی بخشی از برنامه ما است. مثلا پایگاه داده MySQL در یک container است و اسکریپت هایمان در یک container دیگر قرار دارند و الی آخر. Github actions به ما اجازه می دهند تا تست هایی را برای چنین برنامه هایی بنویسیم بدون اینکه نیاز به کار خاصی باشد.

قالب های آماده: github قالب های CI آماده زیادی را برای انواع برنامه ها تدارک دیده است. به همین دلیل شروع یک CI با استفاده از github actions بسیار ساده تر از ایجاد تنظیمات به صورت دستی است. البته در نظر داشته باشید که شما می توانید قالب خودتان را نیز بسازید و سپس آن را در Github Marketplace با دیگر توسعه دهندگان به اشتراک بگذارید.

رایگان: github چند پلن مختلف را برای استفاده از github actions دارد. برخی از این برنامه ها هزینه پرداخت دارند اما یک برنامه رایگان نیز در اختیار تمام پروژه های متن باز قرار می گیرد. اگر پروژه شما متن باز باشد github actions  شامل ۲۰۰۰ دقیقه build رایگان در ماه و ۵۰۰ مگابایت حجم است که برای پروژه های کوچک و متوسط و حتی بعضا پروژه های بزرگ کاملا کفایت می کند. طبیعتا اگر نیاز به build time بیشتری دارید می توانید هزینه آن را بپردازید یا اینکه از سرور خودتان استفاده کنید.

مفاهیم اولیه GitHub Actions

در این بخش می خواهیم با برخی از مفاهیم و اصطلاحات خاص GitHub actions آشنا بشویم تا در هنگام انجام بخش های فنی دچار مشکل نشوید.

Workflow: هر workflow (جریان کاری) شامل پروسه ای خودکار است و با یک رویداد شروع می شود. زمانی که این پروسه خودکار شروع شود، ممکن است یک یا چند عملیات خاص را انجام بدهد. برای تعریف یک workflow در گیت هاب باید پوشه ای به نام github/workflows. در repository خود بسازید و سپس یک فایل YAML را در آن قرار دهید. این فایل، پروسه خودکار workflow را توصیف می کند.

Actions: عملیات ها یا action ها کوچک ترین واحد سازنده یک workflow هستند. شما با ترکیب کردن این action ها می توانید یک job را بسازید. شما می توانید با ترکیب کردن action ها یک step را برای job بسازید. همچنین می توانید action های خودتان را ساخته و یا از action های موجود در GitHub Marketplace استفاده کنید.

Job: هر job یا «کار» از چندین step ساخته شده است. job ها می توانند مستقل از هم اجرا شوند. البته اگر یک job به job دیگری وابسته باشد می توانید آن ها را به صورت توالی نیز اجرا کنید.

Step: هر step یا «قدم» مجموعه ای از عملیات ها است که توسط یک job اجرا می شود. هر step می تواند یک command یا یک action را اجرا کند.

Event: هر event یا رویداد باعث اجرا شدن یک workflow می شود. به طور مثال اگر فردی کدی را به repository ارسال (push) کند یا اگر کسی یک pull request ایجاد کند یک رویداد فعال می شود چرا که هر کدام از این عملیات ها یک رویداد است.

Runner: هر runner یک برنامه است که GitHub actions را اجرا می کند. در واقع runner منتظر می شود تا job های مورد نظرش را پیدا کند. زمانی که یک job انتخاب شد ابتدا action های آن اجرا می شوند و سپس نتیجه را به گیت هاب گزارش می دهد. شما می توانید به دو شکل به runner ها دسترسی داشته باشید؛ در حالت اول از وب سایت گیت هاب استفاده می کنید و همانطور که گفتم این استفاده تا ۲۰۰۰ دقیقه در ماه رایگان است. در حالت دوم runner را روی سرور شخصی خودتان نصب می کنید تا محدودیت زمانی نداشته باشید. حالت دوم معمولا فقط برای پروژه های بسیار بزرگ استفاده می شود.

استفاده از workflow و قالب های action

ساده ترین راه استفاده از workflow ها این است که به Github Marketplace رفته و از قالب های آماده در آن استفاده کنید. تمام این قالب های آماده رایگان هستند. اگر مطمئن نیستید که چه قالبی برای برنامه شما مناسب است، نگاهی به بخش پیشنهادات گیت هاب در این زمینه داشته باشید. گیت هاب سعی می کند بر اساس کدهای repository یک action مناسب را پیشنهاد بدهد.

اولین قدم برای این کار این است که به repository خودتان بروید. در بخش بالای repository گزینه های مختلفی وجود دارد که یکی از آن ها actions نام دارد:

زمانی که روی این گزینه کلیک کنید انواع قالب های آماده را برای workflow هایتان می بینید که توسط گیت هاب پیشنهاد شده اند:

شما می توانید با کلیک روی لینک Skip this and set up a workflow yourself یک workflow را برای خودتان تعریف کرده و از workflow های آماده استفاده نکنید اما من از یک workflow آماده استفاده می کنم (تصویر بالا). زمانی که روی گزینه set up this workflow کلیک کنید صفحه ای برایتان باز می شود تا در صورت نیاز قالب workflow را ویرایش کنید. در بسیاری از اوقات پیش می آید که یک workflow مناسب پروژه شما است اما یکی از عملیات های آن اضافی است یا کار را خراب می کند. شما در این بخش می توانید به راحتی آن را ویرایش کنید:

پس از ویرایش روی دکمه start commit کلیک کنید تا این فایل جدید در پروژه شما commit شود.

اضافه کردن action به workflow

چه زمانی که بخواهید از قالب های آماده استفاده کنید و چه زمانی که بخواهید خودتان یک workflow را تعریف کنید به action های GitHub Marketplace دسترسی خواهید داشت که در سمت راست صفحه هستند:

زمانی که روی یکی از این action ها کلیک می کنید، کد آن برایتان نمایش داده می شود. شما باید این کد نمایش داده شده را در فایل yaml خود کپی کنید. یک مثال از این کدها:

- name: Cache

  uses: actions/cache@v2.1.6

  with:

    # A list of files, directories, and wildcard patterns to cache and restore

    path:

    # An explicit key for restoring and saving the cache

    key:

    # An ordered list of keys to use for restoring the cache if no cache hit occurred for key

    restore-keys: # optional

    # The chunk size used to split up large files during upload, in bytes

    upload-chunk-size: # optional

فیلد name حتما باید یکتا (غیر تکراری) باشد و همچنین حتما نسخه آن action خاص را در قسمت use مشخص کنید. این کار معمولا به صورت خودکار انجام شده است و من از جنبه تذکر آن را یادآوری کرده ام.

نحو و ساختار فایل yaml

چه بخواهید خودتان یک workflow را بسازید و چه بخواهید از قالب های آماده استفاده کنید، با فایل yaml سر و کار خواهید داشت بنابراین باید با ساختار و syntax (نحو) آن آشنا شوید. در ابتدا باید بگویم که نام فایل yaml اهمیتی ندارد، تنها چیزی که مهم است این است که درون پوشه ای به نام github/workflows. در repository شما باشد. مثالی ساده از یک فایل yaml برای تعریف workflow:

.github/workflows/continuous-deployment.yml

بنابراین تمام GitHub Action ها باید درون فایل های yaml نوشته شوند بنابراین پسوند فایل شما باید yml یا yaml باشد (هر دو صحیح هستند). توجه داشته باشید که فایل های yaml مانند هر فایل دیگری (مثلا JSON) فرمت خاص خودشان را دارند بنابراین می توانید ساختار کلی آن ها را سریعا یاد بگیرید. باید بدانید که yaml یک superset برای json است که یعنی دقیقا مانند json است با این تفاوت که قابلیت هایی را به آن اضافه می کند. چیزی که ما در این بخش بررسی خواهیم کرد ساختار فایل های yaml نیست بلکه ساختار خاص فایل های yaml برای ایجاد GitHub Actions است بنابراین من بدیهیات را توضیح نداده و فرض می کنم شما با ساختار yaml آشنا هستید.

خصوصیات بسیار زیادی در فایل yaml برای GitHub Actions وجود دارد. من می خواهم در این بخش مهم ترین این خصوصیات را بررسی کنیم.

خصوصیت Name: این بخش نام workflow شما را مشخص می کند که در صفحه actions برایتان نمایش داده می شود. در صورتی که این خصوصیت را مشخص نکنید، نام workflow به صورت خودکار روی نام فایل yaml تنظیم می شود. مثال استفاده:

name: Continuous Deployment

طبیعتا نام workflow مبحثی سلیقه ای است و می توانید هر چیزی را برایش انتخاب کنید.

خصوصیت On: طبیعتا workflow باید در موارد خاصی اجرا شود و قبلا هم توضیح دادم که workflow ها رویداد محور هستند، یعنی با منتشر شدن رویداد های خاصی اجرا می شوند. در این بخش باید رویداد (event) هایی را مشخص کنید که باعث اجرا شدن این workflow می شوند. مثلا اگر بخواهیم workflow فقط هنگامی اجرا شود که کد جدیدی را push می کنیم باید مقدار on را روی push بگذاریم:

on: push

اگر بخواهیم workflow در هنگام pull request ها و همچنین در هنگام ایجاد issue های جدید اجرا شود نیز باید به شکل زیر عمل کنیم:

on: [pull_request, issues]

خصوصیت Jobs: قبلا هم توضیح دادم که هر workflow از یک یا چند job ساخته شده است. job هایی که شما در این بخش تعریف می کنید به صورت پیش فرض به صورت موازی اجرا می شوند، یعنی منتظر یکدیگر نمانده و مستقل هستند. یک مثال ساده از job ها:

jobs:

  my-job:

    name: My Job

    runs-on: ubuntu-latest

    steps:

    - name: Print a greeting

      run: |

        echo Hello there!

خصوصیت Env: این خصوصیت مخفف environment variable یا متغیر های محیطی است. این متغیر ها در تمام job ها و در تمام step ها قابل دسترسی هستند. البته شما می توانید آن ها را طوری تنظیم کنید که فقط در یک بخش خاص در دسترس باشند. یک مثال ساده از ENV ها:

env:

  CI: true

خصوصیت Runs-on: در مرحله بعدی باید مطمئن بود که workflow شما برای سیستم عامل خاصی کار می کند. مثلا اگر برنامه خود را برای ویندوز نوشته اید طبیعتا باید کدهایتان را در ویندوز تست کنید، اگر برای لینوکس و ویندوز است باید کدها را در هر دو تست کنید و الی آخر. این کار با Runs-on انجام می شود:

runs-on: ubuntu-latest

من در کد بالا کدها را فقط در آخرین نسخه Ubuntu (لینوکس) تست کرده ام اما می توانید با کلیدواژه strategy کدها را روی چندین سیستم عامل تست کنید:

runs-on: ${{ matrix.os }}

strategy:

  matrix:

    os: [ubuntu-16.04, ubuntu-18.04]

    node: [6, 8, 10]

این کد نسخه های ۶ و ۸ و ۱۰ از node را روی دو نسخه ۱۸ و ۱۶ از ubuntu تست می کند. شما می توانید اطلاعات بیشتر در این رابطه را در documentation رسمی گیت هاب مطالعه کنید.

با جست و جویی ساده می توان انواع و اقسام این دستورات را پیدا کرد. یک مثال ساده از یک فایل yaml:

name: 'Hello World'

description: 'Greet someone and record the time'

inputs:

  who-to-greet: 

    description: 'Who to greet'

    required: true

    default: 'World'

outputs:

  time:

    description: 'The time we greeted you'

runs:

  using: 'node12'

  main: 'index.js'

از آنجایی که نحوه استفاده از GitHub Action ها به شدت به پروژه شما وابسته است من نمی توانم توضیحات بیشتری را در حالت کلی بدهم اما همین میزان از اطلاعات مقدماتی باید شما را آماده کار با آن ها کند.

منبع: وب سایت gabrieltanner