Skip to main content

راهنمای استفاده از Github Actions

این مستند شامل اطلاعات مفید در رابطه با کانفیگ های github/workflows/main.yaml. میباشد. (برگرفته از مستندات رسمی Github Actions)

مقدمه​

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

برای استفاده از Github Actions نیاز به ایجاد یک فایل به اسم main.yaml در آدرس github/workflows. در ریپوی خود دارید. پس از ایجاد این فایل در این آدرس, نیاز است طی دو مرحله اصلی اپ خود را بیلد گرفته و در دارکوب دیپلوی کنید.

آشنایی با keywordهای پرکاربرد​

jobs​

از jobs برای مشخص کردن مراحل خود در Github Actions استفاده کنید. به طور مثال شما برای استفاده از Github Actions در دارکوب نیاز به بیلد و دیپلوی اپ خود دارید که میتوانید این دو مرحله را به صورت زیر مشخص کنید.

jobs:
  build:
    # job detail
  darkube-deploy:
    # job detail

runs-on​

از runs-on برای انتخاب کردن os مورد نظر در فرآیند CI/CD خود استفاده کنید.

اگر تمایل به استفاده از رانرهای خود گیتهاب دارید میبایست از یکی از مقادیر زیر استفاده کنید:

  • ubuntu-latest یا ubuntu-VERSION
  • macos-latest یا macos-VERSION
  • windows-latest یا windows-VERSION

VERSION را با ورژن مورد نظر خود جایگزین کنید.

به طور مثال به صورت زیر از runs-on میتوانید استفاده کنید.

jobs:
  build:
    runs-on: ubuntu-latest # choose os to run on (for linux use ubuntu-latest)
    # more job details
  darkube-deploy:
    runs-on: unbuntu-latest # choose os to run on (for linux use ubuntu-latest)
    # more job details

needs​

از needs برای مشخص کردن jobهای مرتبط به job فعلی استفاده کنید. به طور مثال برای دیپلوی در دارکوب نیاز دارید که اول build انجام شود.

jobs:
  build:
    runs-on: ubuntu-latest # choose os to run on (for linux use ubuntu-latest)
    # more job details
  darkube-deploy:
    needs: build # choose dependent jobs you need to run before this job
    runs-on: unbuntu-latest # choose os to run on (for linux use ubuntu-latest)
    # more job details

container​

از container برای مشخص کردن داکر ایمیجی که میخواهید هنگام اجرای job استفاده شود استفاده کنید. به طور مثال برای دیپلوی در دارکوب نیاز دارید از ایمیج hamravesh.hamdocker.ir/public/darkube-cli:v1.1 استفاده کنید.

jobs:
  build:
    runs-on: ubuntu-latest # choose os to run on (for linux use ubuntu-latest)
    # more job details
  darkube-deploy:
    needs: build # choose dependent jobs you need to run before this job
    runs-on: unbuntu-latest # choose os to run on (for linux use ubuntu-latest)
    container: hamravesh.hamdocker.ir/public/darkube-cli:v1.1 # docker container to run steps on.
    # more job details

steps​

از steps برای مشخص کردن stepهای مورد نیاز در اجرای job استفاده کنید. مراحل کامندهای خود را در این keyword باید مشخص کنید. به طور مثال برای بیلد و دیپلوی در دارکوب نیاز به stepهای زیر دارید.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Run script
        run: |
          docker login $REGISTRY -u $REGISTRY_USER -p $REGISTRY_PASSWORD
          docker build -t "$IMAGE:${GITHUB_SHA:0:7}" .
          docker push "$IMAGE:${GITHUB_SHA:0:7}"
        env:
          REGISTRY: ${{ vars.REGISTRY }}
          REGISTRY_PASSWORD: ${{ vars.REGISTRY_PASSWORD }}
          REGISTRY_USER: ${{ vars.REGISTRY_USER }}
          APP_NAME: ${{ vars.APP_NAME }}
          IMAGE: ${{ vars.REGISTRY }}/${{ vars.APP_NAME }}
  darkube_deploy:
    needs: build
    container: hamravesh.hamdocker.ir/public/darkube-cli:v1.1
    runs-on: ubuntu-latest
    steps:
      - name: Run script
        run: darkube deploy --ref master --token ${DARKUBE_DEPLOY_TOKEN} --app-id ${DARKUBE_APP_ID}  --image-tag "${GITHUB_SHA:0:7}" --job-id "$GITHUB_RUN_ID" --stateless-app true
        env:
          DARKUBE_DEPLOY_TOKEN: ${{ vars.DARKUBE_DEPLOY_TOKEN }}
          DARKUBE_APP_ID: ${{ vars.DARKUBE_APP_ID }}

به step اول build توجه کنید. این step در صورتی که شما تمایل به استفاده از داکر ایمیج برای اجرای job نداشته باشید الزامی است.

Run کردن jobهای تعریف شده به صورت CI/CD Pipeline​

شما میتوانید با استفاده از کانفیگ زیر jobهای خود را به صورت CI/CD Pipline اجرا کنید تا با پوش کردن روی برنچ مورد نظر jobهای شما Run شود.

jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - name: Checkout code
        uses: actions/checkout@v2
      - name: Run script
        run: |
          docker login $REGISTRY -u $REGISTRY_USER -p $REGISTRY_PASSWORD
          docker build -t "$IMAGE:${GITHUB_SHA:0:7}" .
          docker push "$IMAGE:${GITHUB_SHA:0:7}"
        env:
          REGISTRY: ${{ vars.REGISTRY }}
          REGISTRY_PASSWORD: ${{ vars.REGISTRY_PASSWORD }}
          REGISTRY_USER: ${{ vars.REGISTRY_USER }}
          APP_NAME: ${{ vars.APP_NAME }}
          IMAGE: ${{ vars.REGISTRY }}/${{ vars.APP_NAME }}
  darkube_deploy:
    needs: build
    container: hamravesh.hamdocker.ir/public/darkube-cli:v1.1
    runs-on: ubuntu-latest
    steps:
      - name: Run script
        run: darkube deploy --ref master --token ${DARKUBE_DEPLOY_TOKEN} --app-id ${DARKUBE_APP_ID}  --image-tag "${GITHUB_SHA:0:7}" --job-id "$GITHUB_RUN_ID" --stateless-app true
        env:
          DARKUBE_DEPLOY_TOKEN: ${{ vars.DARKUBE_DEPLOY_TOKEN }}
          DARKUBE_APP_ID: ${{ vars.DARKUBE_APP_ID }}

name: CI/CD Pipeline
"on":
  push:
    branches:
      - master

توجه کنید که در کانفیگ بالا نام برنچ مورد نظر خود را با master, در بخش های CI/CD Pipline و darkube_deploy عوض کنید.

jobs:
  darkube_deploy:
    steps:
      - name: Run script
        run: darkube deploy --ref <Branch Name> ...
name: CI/CD Pipline
"on":
  push:
    branches:
      - <Branch Name>

همچنین نیاز است که با توجه به مستند تنظیم متغیر در Github Actions، متغیرهای لازم را در سطح ریپوی خود تنظیم کنید.

  • REGISTRY: آدرس رجیستری شما که میتوانید آن را از قسمت کانتینر رجیستری کنسول خود دریافت کنید.
  • REGISTRY_USER: یوزرنیم رجیستری شما که میتوانید آن را از قسمت کانتینر رجیستری کنسول خود دریافت کنید.
  • REGISTRY_PASSWORD: پسورد رجیستری شما که میتوانید آن را از قسمت کانتینر رجیستری کنسول خود دریافت کنید.
  • APP_NAME: نام اپ شما در دارکوب.
  • DARKUBE_DEPLOY_TOKEN: دیپلوی توکن شما که میتوانید آن را از صفحه مشخصات اپ در کنسول دارکوب خود دریافت کنید.
  • DARKUBE_APP_ID: شناسه اپ شما میباشد که میتوانید آن را از صفحه مشخصات اپ در کنسول دارکوب خود, قسمت بالا سمت راست, کپی شناسه اپ کپی کنید.

اگر سوال و یا ابهامی در رابطه با نوشتن فایل github/workflows/main.yaml. داشتید, آن را از طریق تیکت, با تیم پشتیبانی هم‌روش مطرح کنید.

دیپلوی از طریق curl​

در صورت تمایل می‌توانید به جای darkube-cli، صرفا اندپوینت زیر را در اسکریپت جاب دیپلوی فراخوانی کنید:

PUT https://api.console.hamravesh.ir/api/v1/darkube/apps/update_from_cli/
{
    "trigger_deploy_token": # دیپلوی توکن
    "app_id": # شناسه اپ,
    "image_tag": # تگ ایمیج,
}

اطلاعات مربوط به دیپلوی توکن و شناسه اپ در صفحه مشخصات اپ قابل دستیابی هستند.