קביעת תצורה של זרימת עבודה של פעולות GitHub

הושלמה

כאן, תלמד כמה תצורות נפוצות בתוך קובץ זרימת עבודה. בנוסף, אתה מסייר בקטגוריות של סוגי אירועים, הופך זרימות עבודה ללא זמינות ומחיקתן, ו משתמש בגירסאות ספציפיות של פעולה לשיטות עבודה מומלצות לאבטחה.

קביעת תצורה של זרימות עבודה להפעלה עבור אירועים מתוזמנים

כפי שצוין קודם לכן, באפשרותך לקבוע את תצורת זרימות העבודה שלך כך שיפעלו כאשר פעילות מסוימת מתרחשת ב- GitHub, כאשר מתרחש אירוע מחוץ ל- GitHub או בזמן מתוזמן. אירוע schedule מאפשר לך להפעיל זרימת עבודה במועדי UTC ספציפיים באמצעות תחביר cron של POSIX. תחביר cron זה מכיל חמישה * שדה, וכל שדה מייצג יחידת זמן.

לדוגמה, אם ברצונך להפעיל זרימת עבודה כל 15 דקות, האירוע schedule ייראה כמו הדוגמה הבאה:

on:
  schedule:
    - cron:  '*/15 * * * *'

ואם רצית להפעיל זרימת עבודה בכל יום ראשון בשעה 03:00, schedule האירוע ייראה כך:

on:
  schedule:
    - cron:  '0 3 * * SUN'

באפשרותך גם להשתמש באופרטורים כדי לציין טווח ערכים או כדי לחייג בזרימת העבודה המתוזמנת שלך. המרווח הקצר ביותר שבו באפשרותך להפעיל זרימות עבודה מתוזמנות הוא פעם אחת כל חמש דקות, והן פועלות על ההשלמה האחרונה בענף ברירת המחדל או הבסיס.

קביעת תצורה של זרימות עבודה להפעלה עבור אירועים ידניים

בנוסף לאירועים מתוזמנים, באפשרותך להפעיל זרימת עבודה באופן ידני באמצעות workflow_dispatch זה. אירוע זה מאפשר לך להפעיל את זרימת העבודה באמצעות ממשק ה- REST API של GitHub או על-ידי בחירה בלחצן הפעל זרימת עבודה בכרטיסיה פעולות של בתוך המאגר שלך ב- GitHub. באמצעות workflow_dispatch, באפשרותך לבחור באיזה ענף ברצונך שזרימת העבודה תפעיל, inputs ולהגדיר אופציונלי ש- GitHub מציג כרכיבים בטופס בממשק המשתמש.

on:
  workflow_dispatch:
    inputs:
      logLevel:
        description: 'Log level'     
        required: true
        default: 'warning'
      tags:
        description: 'Test scenario tags'  

בנוסף ל- workflow_dispatch, באפשרותך להשתמש ב- API של GitHub כדי להפעיל אירוע webhook שנקרא repository_dispatch. אירוע זה מאפשר לך להפעיל זרימת עבודה עבור פעילות המתרחשת מחוץ ל- GitHub. הוא משמש למעשה כבקשה HTTP למאגר שלך המבקשת מ- GitHub להפעיל זרימת עבודה מפעולה או מ- webhook. השימוש באירוע ידני זה דורש ממך לבצע שתי פעולות: שלח בקשת POST אל נקודת הקצה של GitHub /repos/{owner}/{repo}/dispatches עם שמות האירועים של ה- webhook בגוף הבקשה והגדר את זרימת העבודה שלך לשימוש באירוע repository_dispatch.

curl \
  -X POST \
  -H "Accept: application/vnd.github.v3+json" \
  https://api.github.com/repos/octocat/hello-world/dispatches \
  -d '{"event_type":"event_type"}'

on:
  repository_dispatch:
    types: [opened, deleted]

קביעת תצורה של זרימות עבודה להפעלה עבור אירועי Webhook

לבסוף, באפשרותך לקבוע תצורה של זרימת עבודה להפעלה כאשר מתרחשים אירועים ספציפיים של webhook ב- GitHub. באפשרותך להפעיל את רוב אירועי webhook מתוך יותר מפעילות אחת עבור webhook. אם קיימות פעילויות מרובות עבור webhook, באפשרותך לציין סוג פעילות שיפעיל את זרימת העבודה. לדוגמה, באפשרותך להפעיל זרימת עבודה עבור האירוע check_run , אך רק עבור סוגי rerequested הפעילות requested_action או.

on:
  check_run:
    types: [rerequested, requested_action]

Repository_dispatch

repository_dispatch הוא אירוע מותאם אישית בפעולות GitHub המאפשר למערכות חיצוניות (או אפילו זרימות עבודה אחרות של GitHub) להפעיל זרימות עבודה באופן ידני על-ידי שליחת בקשת POST ל- API של GitHub. הוא מאפשר אוטומציה ושילוב גמישים עם כלים חיצוניים, קבצי Script או מערכות שיש להפעיל זרימות עבודה ב- repo שלך.

מקרי שימוש

• הפעל זרימות עבודה מכלי CI/CD חיצוניים.

• תאם פריסות מרובות repo (לדוגמה, Repo A מסיים את גירסת ה- Build → מפעילים Repo B).

• התחל אוטומציה בהתבסס על אירועים חיצוניים (webhooks, התראות ניטור, משימות CRON מחוץ ל- GitHub).

• ביצועי זרימת עבודה של שרשרת בין מאגרים או בתוך מונורה.

זרימת עבודה לדוגמה שמאזין repository_dispatch

name: Custom Dispatch Listener

on:
  repository_dispatch:
    types: [run-tests, deploy-to-prod]  # Optional filtering

jobs:
  run:
    runs-on: ubuntu-latest
    steps:
      - name: Echo the payload
        run: |
          echo "Event type: ${{ github.event.action }}"
          echo "Payload value: ${{ github.event.client_payload.env }}"

רכיבי מפתח:

• סוגים: אופציונלי. הגדרת סוגי אירועים מותאמים אישית כגון run-tests, deploy-to-prod, וכו'.

• github.event.client_payload: גישה לנתונים מותאמים אישית אחרים שהועברו באירוע שיגור.

• github.event.action: שם event_type נשלח.

הפעלת האירוע באמצעות API

עליך לשלוח בקשת POST אל נקודת הקצה של REST API v3 של GitHub:

POST https://api.github.com/repos/OWNER/REPO/dispatches

ההרשאות

• נדרש אסימון גישה אישי (PAT) עם טווח repo.
• עבור ארגונים, ודא את הגדרות הגישה המתאימות עבור האסימון שלך.

מבנה פקודה לדוגמה

curl -X POST \
  -H "Accept: application/vnd.github+json" \
  -H "Authorization: token YOUR_GITHUB_TOKEN" \
  https://api.github.com/repos/OWNER/REPO/dispatches \
  -d '{"event_type":"run-tests","client_payload":{"env":"staging"}}'

מבנה תוכן מנה

{
  "event_type": "run-tests",
  "client_payload": {
    "env": "staging"
  }
}

פרמטרים

שדה	סוג	תיאור	נדרש
event_type	מחרוזת	שם מותאם אישית עבור האירוע. שם זה ממפה לערך הסוגים במפעיל זרימת העבודה שלך	כן
client_payload	אובייקט	תוכן מנה של JSON שרירותי לשליחת נתונים מותאמים אישית לזרימת העבודה (github.event.client_payload)	לא

Repository_dispatch התפלגות פרמטרים

בעת ביצוע בקשת POST אל נקודת הקצה של API של GitHub, עליך להעביר גוף JSON עם שני פרמטרים עיקריים:

• event_type
• client_payload

event_type

מחרוזת מותאמת אישית נדרשת שאתה מגדיר. GitHub מתייחס לערך זה כ"פעולה" או "סוג" של שיגור. הוא משמש לזיהוי הפריטים שהפעילו את זרימת העבודה וסינון זרימות עבודה שמאזינים לסוגים ספציפיים.

• תבנית:

  • סוג: מחרוזת
  • דוגמה: "deploy", "run-tests", "sync-db", "build-docker"

• השתמש בזרימת עבודה: משמש להאזנה לסוגי אירועים ספציפיים וגישה לערך בתוך זרימת העבודה. פעולה זו מסייעת לעשות שימוש חוזר בזרימת עבודה בודדת למטרות מרובות והופכת את האוטומציה לארגון יותר ולמונעת על-ידי אירועים.

• דוגמה:

- name: Print event type
  run: echo "Event type: ${{ github.event.action }}"

client_payload

אובייקט JSON חופשי המאפשר לך לשלוח נתונים מותאמים אישית יחד עם שיגור. אתה מגדיר את המבנה, והוא נגיש בתוך זרימת העבודה.

• תבנית:

  • סוג: אובייקט
  • מפתחות וערכים מותאמים אישית

• שימוש בזרימת עבודה: אובייקט זה משמש עבור פריסות מרובות סביבה, מהדורות גרסאות או העברת הקשר ממערכת או צינור אחרים ומאפשר זרימות עבודה עם פרמטרים, בדומה לארגומנטים של קלט.

• דוגמה:

- name: Show payload values
  run: |
    echo "Environment: ${{ github.event.client_payload.env }}"
    echo "Version: ${{ github.event.client_payload.version }}"

פירוט תוכן מנה לדוגמה

{
  "event_type": "deploy-to-prod",
  "client_payload": {
    "env": "production",
    "build_id": "build-456",
    "initiator": "admin_user",
    "services": ["web", "api", "worker"]
  }
}

שימוש במילות מפתח מותנים

בתוך קובץ זרימת העבודה, באפשרותך לגשת למידע הקשר ולהעריך ביטויים. אף על פי שביטויים נמצאים בשימוש לעתים קרובות עם מילת המפתח if מותנה בקובץ זרימת עבודה כדי לקבוע אם שלב צריך לפעול או לא, באפשרותך להשתמש בכל הקשר וביטוי נתמכים כדי ליצור מותנה. חשוב לדעת ש בעת שימוש במותנים בזרימת העבודה שלך, עליך להשתמש בתחביר הספציפי ${{ <expression> }}. תחביר זה מורה ל- GitHub להעריך ביטוי במקום להתייחס אליו כמחרוזת.

לדוגמה, זרימת עבודה המשתמשת ifgithub.ref במותנה כדי לבדוק אם (ההסתעפות או ה- ref של התג שהפעיל את זרימת העבודה) תואמים refs/heads/mainל- . כדי להמשיך, זרימת העבודה תיראו בערך כך:

name: CI
on: push
jobs:
  prod-check:
    if: github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
      ...

שים לב שבדוגמה זו, ${{ }} חסרים בתחביר. באמצעות ביטויים מסוימים, כגון if המותנה, באפשרותך להשמיט את תחביר הביטוי. GitHub מעריך באופן אוטומטי חלק מהביטויים הנפוצים הללו, אך ניתן תמיד לכלול אותם למקרה שתשכח אילו ביטויים GitHub מעריך באופן אוטומטי.

לקבלת מידע נוסף אודות תחביר זרימת עבודה וביטויים, עיין בתחביר זרימת עבודה עבור פעולות GitHub.

ביטול ומחיקה של זרימות עבודה

לאחר הוספת זרימת עבודה למאגר שלך, ייתכן שתמצא מצב שבו ברצונך להפוך את זרימת העבודה ללא זמינה באופן זמני. באפשרותך להפסיק הפעלה של זרימת עבודה מבלי שתצטרך למחוק את הקובץ מה- repo, ב- GitHub או באמצעות ממשק ה- REST API של GitHub. כאשר ברצונך להפוך את זרימת העבודה לזמינה שוב, תוכל לעשות זאת בקלות באמצעות אותן שיטות.

הפיכת זרימת עבודה ללאזמינה יכולה להיות שימושית בחלק מהמצבים הבאים:

• שגיאה בזרימת עבודה מייצרת בקשות רבות מדי או שגויות המשפיעות על שירותים חיצוניים בצורה שלילית.
• ברצונך להשהות באופן זמני זרימת עבודה שאינה קריטית וצורכת דקות רבות מדי בחשבון שלך.
• ברצונך להשהות זרימת עבודה השולחת בקשות לשירות שאינו פועל.
• אתה עובד על מזלג ואינך זקוק לכל הפונקציונליות של חלק מזרימות העבודה שהוא כולל (כגון זרימות עבודה מתוזמנות).

באפשרותך גם לבטל הפעלה של זרימת עבודה המתבצעת בממשק המשתמש של GitHub מהכרטיסיה Actions או באמצעות נקודת הקצה של API של GitHub DELETE /repos/{owner}/{repo}/actions/runs/{run_id}. זכור כי בעת ביטול הפעלת זרימת עבודה, GitHub מבטל את כל המשימות והפעולות שלה במסגרת הפעלה זו.

שימוש בזרימת עבודה בתבנית של ארגון

אם יש לך זרימת עבודה שבה צוותים מרובים משתמשים בתוך ארגון, אינך צריך ליצור מחדש את אותה זרימת עבודה עבור כל מאגר. במקום זאת, באפשרותך לקדם עקביות ברחבי הארגון באמצעות תבנית זרימת עבודה המוגדרת .github במאגר של הארגון. כל חבר בארגון יכול להשתמש בזרימת עבודה של תבנית ארגונית, וכל מאגר בארגון זה יכול לגשת לזרימות עבודה אלה של תבניות.

באפשרותך למצוא זרימות עבודה אלה על-ידי ניווט אל הכרטיסיה פעולות של מאגר בתוך הארגון, בחירה באפשרות זרימת עבודה חדשהולאחר מכן איתור מקטע תבנית זרימת העבודה של הארגון שנקרא "זרימות עבודה שנוצרו על-ידי organization name". לדוגמה, לארגון בשם Mona יש זרימת עבודה של תבנית, כפי שמוצג כאן.

שימוש בגירסאות ספציפיות של פעולה

בעת הפניה לפעולות בזרימת העבודה שלך, מומלץ להפנות לגירסה ספציפית של פעולה זו ולא רק לפעולה עצמה. על-ידי הפניה לגירסה ספציפית, אתה מבצע הגנה מפני שינויים בלתי צפויים שנדחפים לפעולה שעלולה לגרום לפיצול זרימת העבודה שלך. להלן כמה דרכים שבהן תוכל להפנות לגירסה ספציפית של פעולה:

steps:    
  # Reference a specific commit
  - uses: actions/setup-node@c46424eee26de4078d34105d3de3cc4992202b1e
  # Reference the major version of a release
  - uses: actions/setup-node@v1
  # Reference a minor version of a release
  - uses: actions/setup-node@v1.2
  # Reference a branch
  - uses: actions/setup-node@main

הפניות מסוימות בטוחות יותר מאחרות. לדוגמה, הפניה לענף ספציפי מפעילה את הפעולה מחוץ לשינויים האחרונים מענף זה, שייתכן שתרצה או לא תרצה. על-ידי הפניה למספר גירסה ספציפית או ביצוע קוד Hash של SHA, אתה מתייחס באופן ספציפי יותר לגירסת הפעולה שאתה מפעיל. לקבלת יציבות ואבטחה נוספות, מומלץ להשתמש ב- SHA לביצוע של פעולה שפורסמה בתוך זרימות העבודה שלך.