GitHub API ו-Webhooks — גישה תכנותית

8.1 נוף ה-API של GitHub — שלוש דרכי גישה

כל דבר שעושים בממשק הגרפי של GitHub — פתיחת issue, מיזוג PR, יצירת release — אפשר לעשות דרך ה-API. ולא רק אפשר — חובה, אם רוצים אוטומציות אמיתיות. הממשק הגרפי מצוין לפעולות בודדות, אבל כשצריכים לעשות משהו על 50 ריפוזיטורים, לבנות dashboard שמרכז מידע, או להגיב אוטומטית לאירועים — ה-API הוא הכלי.

ל-GitHub יש שלוש דרכי גישה תכנותית:

1. REST API — ממשק HTTP קלאסי עם endpoints נפרדים לכל משאב. הבסיס. הכי מתועד. מתאים ל-CRUD פשוט ולרוב המשימות היומיומיות.
2. GraphQL API — שפת שאילתות מתקדמת. מבקשים בדיוק את השדות שצריכים, בקריאה אחת. מושלם לשאילתות מורכבות שמערבות nested data.
3. gh api — הפקודה מ-GitHub CLI (פרק 2) שנותנת גישה מיידית לשניהם, בלי להתעסק עם tokens ידנית. הדרך המהירה ביותר לבדוק ולנסות.

מתי צריכים API? כל פעם שה-UI לא מספיק:

• אוטומציות — בוט שמגיב ל-PRs, סקריפט שפותח issues לפי תבנית, כלי שמסמן PRs ללא reviewers
• דשבורדים — מסך שמרכז מידע מכמה ריפוזיטורים: כמה PRs פתוחים, מה הזמן הממוצע ל-merge, אילו issues תקועים
• אינטגרציות — חיבור GitHub ל-Slack, Jira, מערכת ניטור פנימית, או CRM
• ניהול בקנה מידה — פעולות על 50 ריפוזיטורים בו-זמנית: עדכון dependabot.yml, שינוי branch protection rules, ניקוי stale branches

גרסת API נוכחית: ב-מרץ 2026 שוחררה גרסה 2026-03-10, אבל ברירת המחדל נשארת 2022-11-28 לתאימות אחורית. כדי להשתמש בגרסה החדשה, מוסיפים header:

X-GitHub-Api-Version: 2026-03-10

שינויים שבורים בגרסה החדשה כוללים, בין היתר: submodules מסומנים כ-type: "submodule" במקום "file", הסרת use_squash_pr_title_as_default, ועוד. אם אתם לא צריכים את השינויים — עדיף להישאר עם ברירת המחדל עד שהכלים שלכם מוכנים.

gh api /rate_limit --jq '.resources.core | "Limit: \(.limit), Remaining: \(.remaining), Reset: \(.reset)"'

8.2 REST API — הבסיס של הכל

ה-REST API של GitHub הוא ממשק HTTP קלאסי: לכל משאב (ריפוזיטורי, issue, PR, user) יש endpoint עם כתובת URL ברורה. הבסיס: https://api.github.com.

מבנה Endpoint:

# רשימת issues בריפוזיטורי
GET /repos/{owner}/{repo}/issues

# issue ספציפי
GET /repos/{owner}/{repo}/issues/{issue_number}

# יצירת issue חדש
POST /repos/{owner}/{repo}/issues

# עדכון issue
PATCH /repos/{owner}/{repo}/issues/{issue_number}

# מחיקת תגובה
DELETE /repos/{owner}/{repo}/issues/comments/{comment_id}

ארבע פעולות HTTP מכסות את הכל:

• GET — קריאה (שליפת נתונים)
• POST — יצירה (משאב חדש)
• PATCH — עדכון (שינוי חלקי)
• DELETE — מחיקה

# שליפת 5 issues אחרונים עם שם ומצב
gh api repos/{owner}/{repo}/issues \
  -q '.[0:5] | .[] | "\(.number) \(.title) [\(.state)]"'

Pagination — עמוד אחרי עמוד:

רוב ה-endpoints מחזירים מקסימום 30 פריטים (ברירת מחדל). אפשר לבקש עד 100 עם per_page:

# 100 issues בעמוד, עמוד 2
gh api repos/cli/cli/issues?per_page=100&page=2 --jq 'length'

# כל העמודים אוטומטית (gh api מטפל ב-pagination)
gh api repos/cli/cli/issues --paginate --jq '.[].title'

ב-REST, ה-pagination עובד עם Link header — GitHub שולח בתשובה את הקישורים לעמוד הבא, הקודם, הראשון והאחרון. הפקודה gh api --paginate עוקבת אחרי ה-links אוטומטית.

סינון ומיון — שולטים במה שחוזר:

# רק issues פתוחים, ממוינים לפי תגובות (הכי מדוברים קודם)
gh api repos/{owner}/{repo}/issues?state=open&sort=comments&direction=desc \
  --jq '.[] | "\(.number) \(.title) — \(.comments) comments"'

# issues שעודכנו בשבוע האחרון
gh api "repos/{owner}/{repo}/issues?state=all&since=$(date -d '7 days ago' -u +%Y-%m-%dT%H:%M:%SZ)" \
  --jq '.[] | "\(.number) \(.title) [\(.state)]"'

# labels ספציפיים
gh api repos/{owner}/{repo}/issues?labels=bug,priority-high \
  --jq '.[] | "#\(.number) \(.title)"'

פרמטרי סינון נפוצים:

• state — open, closed, all
• sort — created, updated, comments
• direction — asc, desc
• since — ISO 8601 timestamp — רק פריטים שעודכנו אחרי התאריך
• labels — סינון לפי labels (מופרדים בפסיקים)
• assignee — סינון לפי מי שמוקצה ל-issue

Response Headers שכדאי להכיר:

• X-RateLimit-Limit — מגבלת הבקשות לשעה (5,000 בדרך כלל)
• X-RateLimit-Remaining — כמה נשארו
• X-RateLimit-Reset — Unix timestamp של האיפוס הבא
• ETag — חותמת גרסה — שמרו אותה ל-conditional requests (סעיף 8.10)
• Link — קישורים ל-pagination: next, prev, first, last

# 1. POST — יצירת issue
gh api repos/{owner}/{repo}/issues \
  -f title="Test Issue from API" \
  -f body="This issue was created via the GitHub REST API" \
  -f labels[]="documentation" \
  --jq '.number'

# 2. PATCH — עדכון (השתמשו במספר שקיבלתם)
gh api repos/{owner}/{repo}/issues/{NUMBER} -X PATCH \
  -f title="Updated: Test Issue from API" \
  -f state=closed

# 3. GET — אימות שזה עבד
gh api repos/{owner}/{repo}/issues/{NUMBER} \
  --jq '"\(.title) [\(.state)]"'

דוגמה מתקדמת — סקריפט שמנקה issues ישנים:

הנה דוגמה מעשית שמשלבת pagination, סינון, ועדכון. הסקריפט מוצא את כל ה-issues שלא עודכנו 90 יום ומוסיף להם label:

# מצאו issues ישנים וסמנו אותם
CUTOFF=$(date -d '90 days ago' -u +%Y-%m-%dT%H:%M:%SZ)
gh api repos/{owner}/{repo}/issues?state=open\&since=2020-01-01T00:00:00Z\&per_page=100 \
  --paginate --jq ".[] | select(.updated_at < \"$CUTOFF\") | .number" | \
  while read NUM; do
    gh api repos/{owner}/{repo}/issues/$NUM -X PATCH -f labels[]="stale"
    echo "Labeled #$NUM as stale"
  done

עוד REST endpoints שימושיים שכדאי להכיר:

• Releases: GET /repos/{owner}/{repo}/releases — רשימת releases, POST ליצירת release חדש
• Branches: GET /repos/{owner}/{repo}/branches — רשימת branches עם protection status
• Collaborators: GET /repos/{owner}/{repo}/collaborators — מי יש לו גישה לריפו
• Actions Workflows: GET /repos/{owner}/{repo}/actions/runs — רשימת ריצות workflow
• Search: GET /search/issues?q=label:bug+state:open — חיפוש חוצה ריפוזיטורים

# חיפוש חוצה ריפוזיטורים: כל ה-issues שמוקצים לכם
gh api "/search/issues?q=assignee:$(gh api /user --jq '.login')+state:open+type:issue" \
  --jq '.items[] | "\(.repository_url | split("/") | .[-1]) #\(.number) \(.title)"'

Status Codes שחשוב להכיר:

כשעובדים עם ה-API, קודי התגובה מספרים את כל הסיפור:

• 200 OK — הצליח. התשובה בגוף ה-response.
• 201 Created — משאב חדש נוצר (POST הצליח).
• 204 No Content — הצליח, אין גוף (DELETE טיפוסי).
• 304 Not Modified — Conditional request — לא השתנה. לא נספר ב-rate limit.
• 401 Unauthorized — Token פג תוקף, לא קיים, או שגוי.
• 403 Forbidden — אין הרשאה, או rate limit exceeded. בדקו את ה-headers.
• 404 Not Found — המשאב לא קיים, או שאין לכם הרשאת קריאה (GitHub מחזיר 404 ולא 403 כדי לא לחשוף קיום ריפוזיטורים פרטיים).
• 422 Unprocessable Entity — ה-JSON שגוי או שדה חובה חסר.
• 429 Too Many Requests — Secondary rate limit. יש Retry-After header.

8.3 GraphQL API — שאילתות חכמות

ב-REST, כל endpoint מחזיר מבנה קבוע — גם אם צריכים רק שדה אחד. ב-GraphQL, אתם קובעים בדיוק מה לקבל. Endpoint אחד: https://api.github.com/graphql. Method אחד: POST. השאלה היחידה היא מה שואלים.

Query — שליפת נתונים:

# שליפת שם המשתמש ו-bio + 5 ריפוזיטורים אחרונים
gh api graphql -f query='
{
  viewer {
    login
    bio
    repositories(first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
      nodes {
        name
        stargazerCount
        primaryLanguage { name }
      }
    }
  }
}'

מה שקורה כאן: בקריאה אחת מקבלים את פרטי המשתמש + 5 ריפוזיטורים אחרונים + כוכבים + שפה ראשית. ב-REST הייתם צריכים שלוש קריאות נפרדות: אחת ל-user, אחת ל-repos, ואחת לכל repo בשביל שפות.

Variables — פרמטרים דינמיים:

במקום להטמיע ערכים ישירות ב-query, משתמשים ב-variables. זה מאפשר לשלוח את אותו query עם פרמטרים שונים, ומונע בעיות injection:

gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 3, states: OPEN) {
      nodes {
        number
        title
        author { login }
        reviews(first: 5) {
          nodes { state }
        }
        files(first: 10) {
          nodes { path additions deletions }
        }
      }
    }
  }
}'

שימו לב: PR + author + reviews + files changed — הכל בבקשה אחת. ב-REST הייתם צריכים 4 קריאות (PR list, כל PR, reviews, files) שכופלות ב-3 PRs = 12 קריאות vs אחת.

Fragments — שימוש חוזר בשדות:

כשיש שדות שחוזרים על עצמם בכמה מקומות ב-query, אפשר להגדיר fragment פעם אחת ולהשתמש בו:

gh api graphql -f query='
fragment RepoInfo on Repository {
  name
  stargazerCount
  isArchived
  primaryLanguage { name }
  defaultBranchRef { name }
}

{
  viewer {
    repositories(first: 3, orderBy: {field: STARGAZERS, direction: DESC}) {
      nodes { ...RepoInfo }
    }
    repositoriesContributedTo(first: 3, contributionTypes: [COMMIT]) {
      nodes { ...RepoInfo }
    }
  }
}'

ה-fragment RepoInfo מגדיר פעם אחת אילו שדות לשלוף מכל repository, ומשמש גם ל-repos שלכם וגם ל-repos שתרמתם אליהם.

Mutation — שינוי נתונים:

# הוספת תגובה ל-issue (צריכים Node ID, לא מספר רגיל)
gh api graphql -f query='
mutation {
  addComment(input: {
    subjectId: "ISSUE_NODE_ID"
    body: "Comment added via GraphQL API"
  }) {
    commentEdge {
      node { body createdAt }
    }
  }
}'

טיפ: ה-subjectId ב-GraphQL הוא Node ID ולא מספר רגיל. Node IDs הם מזהים ייחודיים גלובליים ב-GitHub שמתחילים ב-prefix שמזהה את הסוג — I_ ל-Issue, PR_ ל-Pull Request, R_ ל-Repository. אפשר לשלוף אותם עם REST:

# שליפת Node ID של issue
gh api repos/{owner}/{repo}/issues/{n} --jq .node_id

# שליפת Node ID של ריפוזיטורי
gh api repos/{owner}/{repo} --jq .node_id

חשוב: אם משתמשים ב-mutations (כתיבה) ב-GraphQL, חייבים Node IDs. אם רק קוראים (queries), אפשר להשתמש ב-owner/name הרגילים.

Aliases — שאילתות מקבילות באותו query:

מה אם צריכים לקרוא לאותו field פעמיים עם פרמטרים שונים? ב-GraphQL, משתמשים ב-aliases:

gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    openPRs: pullRequests(states: OPEN) { totalCount }
    mergedPRs: pullRequests(states: MERGED) { totalCount }
    openIssues: issues(states: OPEN) { totalCount }
    closedIssues: issues(states: CLOSED) { totalCount }
  }
}' --jq '.data.repository | "Open PRs: \(.openPRs.totalCount), Merged: \(.mergedPRs.totalCount), Open Issues: \(.openIssues.totalCount), Closed: \(.closedIssues.totalCount)"'

ארבעה מספרים בקריאה אחת. ב-REST הייתם צריכים 4 קריאות נפרדות עם פרמטרי state שונים.

Connections ו-Pagination ב-GraphQL:

ב-GraphQL, pagination עובדת עם cursors, לא עמודים. זה יותר מדויק מ-offset-based pagination ומונע דילוג על פריטים כשנתונים משתנים בזמן ה-pagination:

# שליפת 100 issues עם cursor-based pagination
gh api graphql -f query='
query($cursor: String) {
  repository(owner: "facebook", name: "react") {
    issues(first: 100, after: $cursor, states: OPEN) {
      pageInfo {
        hasNextPage
        endCursor
      }
      nodes {
        number
        title
      }
    }
  }
}'

כדי לעבור לעמוד הבא, שולחים את endCursor כ-variable $cursor בקריאה הבאה. כשה-hasNextPage מחזיר false — סיימתם. היתרון על offset-based pagination (REST): אם נוצרו issues חדשים בזמן שעברתם עמודים, cursor pagination לא תדלג על פריטים ולא תראה כפילויות.

gh api graphql -f query='{
  viewer {
    repositories(first: 5, orderBy: {field: UPDATED_AT, direction: DESC}) {
      nodes { name stargazerCount updatedAt }
    }
  }
}' --jq '.data.viewer.repositories.nodes[] | "\(.name) — \(.stargazerCount) stars"'

דוגמה מעשית — dashboard query:

הנה query שמרכז מידע שימושי לסקירת פרויקט — PRs פתוחים עם סטטוס review, issues קריטיים, ו-releases אחרונים. הכל בקריאה אחת:

gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    openPRs: pullRequests(first: 5, states: OPEN, orderBy: {field: UPDATED_AT, direction: DESC}) {
      totalCount
      nodes {
        number
        title
        author { login }
        reviewDecision
        createdAt
      }
    }
    criticalIssues: issues(first: 5, states: OPEN, labels: ["bug", "critical"]) {
      totalCount
      nodes {
        number
        title
        assignees(first: 1) { nodes { login } }
      }
    }
    latestRelease: releases(first: 1, orderBy: {field: CREATED_AT, direction: DESC}) {
      nodes {
        tagName
        publishedAt
        author { login }
      }
    }
  }
}' --jq '.data.repository'

שימו לב ל-aliases (openPRs, criticalIssues, latestRelease) — הם מאפשרים לקרוא לאותו type כמה פעמים עם פילטרים שונים בקריאה אחת. בלי aliases, GraphQL לא היה מאפשר שני שדות pullRequests באותו query.

ה-query הזה מחליף מה שב-REST היה דורש לפחות 3 קריאות (PRs, issues, releases), ואם הייתם רוצים גם reviewDecision ו-assignees — הייתם צריכים עוד 5+ קריאות. ב-GraphQL: קריאה אחת. 0.2 שניות. בקשת API אחת מתוך 5,000.

# 1. שלפו PRs
gh api repos/{owner}/{repo}/pulls?state=open&per_page=3

# 2. לכל PR — שלפו files
gh api repos/{owner}/{repo}/pulls/{NUMBER}/files --jq 'length'

gh api graphql -F owner='{owner}' -F name='{repo}' -f query='
query($owner: String!, $name: String!) {
  repository(owner: $owner, name: $name) {
    pullRequests(first: 3, states: OPEN) {
      nodes {
        title
        author { login }
        changedFiles
      }
    }
  }
}'

8.4 REST vs GraphQL — מתי מה

שתי הגישות חיות יחד — השאלה היא לא "מה יותר טוב" אלא "מה מתאים למקרה הספציפי".

כלל אצבע: אם אתם כותבים סקריפט CLI מהיר — REST עם gh api. אם אתם בונים dashboard או צריכים nested data — GraphQL. אם אתם לא בטוחים — התחילו עם REST. תמיד אפשר לעבור ל-GraphQL אחר כך.

8.5 אימות — PAT, OAuth ו-GitHub Apps

כל קריאה ל-API צריכה אימות. בלעדיו — מגבלת 60 בקשות לשעה בלבד. עם אימות — 5,000+. אבל יש כמה דרכים, ולא כולן שוות. בואו נכיר את כולן ונבין מתי להשתמש בכל אחת.

1. Fine-grained PAT — הבחירה הנכונה לסקריפטים אישיים:

• הרשאות מדויקות לכל ריפוזיטורי — issues: read, pull_requests: write
• תאריך תפוגה חובה — לא יישאר לנצח אם תשכחו
• מגבלה: 50 tokens לכל משתמש
• Rate limit: 5,000 בקשות/שעה
• שימוש ב-header: Authorization: Bearer ghp_xxxxxxxxxxxx

דוגמה — שימוש ב-fine-grained PAT עם curl:

# שליפת issues עם fine-grained PAT (כשלא משתמשים ב-gh)
curl -s -H "Authorization: Bearer ghp_xxxxxxxxxxxx" \
  -H "Accept: application/vnd.github+json" \
  -H "X-GitHub-Api-Version: 2022-11-28" \
  "https://api.github.com/repos/{owner}/{repo}/issues?state=open&per_page=5" | \
  jq '.[].title'

2. Classic PAT — הימנעו:

ה-Classic PAT משתמש ב-scopes רחבים — repo נותן גישה מלאה לכל הריפוזיטורים שלכם, ציבוריים ופרטיים. אין סיבה להשתמש בו ב-2026. GitHub ממליץ במפורש על fine-grained. Classic PAT לא מגביל לריפוזיטורים ספציפיים, לא דורש תאריך תפוגה (אם כי מומלץ), ומהווה סיכון אבטחה רציני אם דולף — התוקף מקבל גישה לכל הקוד שלכם.

3. OAuth Apps — למי שצריך אימות משתמשים:

• המשתמש נשלח ל-GitHub, מאשר, וחוזר עם code
• תומך ב-PKCE מ-2025 (Proof Key for Code Exchange) — אבטחה משופרת שמונעת code interception
• פועל בשם המשתמש — כל פעולה רשומה תחתיו
• שימוש עיקרי: אפליקציות ווב שצריכות גישה לנתוני המשתמש
• Rate limit: 5,000 בקשות/שעה לכל משתמש מאומת

4. GitHub Apps — ההמלצה לאינטגרציות:

• זהות עצמאית — לא תלויה במשתמש ספציפי. עובד עוזב? ה-App ממשיכה.
• Installation tokens — תוקף שעה אחת, מתחדשים אוטומטית
• Rate limit גבוה: עד 15,000 בקשות/שעה (Enterprise Cloud)
• הרשאות גרנולריות לכל endpoint: issues: write, contents: read
• Webhook events מובנים — ה-App מגדירה אילו events היא מקבלת
• לא צורכת seat — לא נספרת כמשתמש בארגון

5. GITHUB_TOKEN ב-Actions:

• נוצר אוטומטית בכל workflow — לא צריך להגדיר
• גישה לריפוזיטורי הנוכחי בלבד
• Rate limit: 1,000 בקשות/שעה לכל ריפו
• מתאים לכל workflow שפועל בגבולות ריפו אחד

8.6 Webhooks — GitHub מדבר אליכם

עד עכשיו אתם שלחתם בקשות ל-GitHub (pull). עם Webhooks, GitHub שולח הודעות אליכם (push). כל אירוע בריפוזיטורי — push, PR נפתח, issue נסגר, release חדש — יכול לשלוח HTTP POST לשרת שלכם. זה מה שמאפשר לבנות בוטים, התראות, ואוטומציות שמגיבות בזמן אמת.

איך זה עובד:

1. אתם מגדירים URL שלכם ב-Settings → Webhooks
2. אתם בוחרים אילו אירועים מעניינים אתכם
3. GitHub שולח POST עם JSON payload לכל אירוע שקורה
4. השרת שלכם מקבל, מאמת את החתימה, ומגיב תוך 10 שניות

הגדרת Webhook:

# הגדרה דרך ה-UI:
# Settings → Webhooks → Add webhook
# Payload URL: https://your-server.com/webhook
# Content type: application/json
# Secret: YOUR_STRONG_RANDOM_SECRET
# Events: "Let me select individual events" → Pull requests, Issues

# או דרך ה-API:
gh api repos/{owner}/{repo}/hooks -f name=web \
  -f config[url]="https://your-server.com/webhook" \
  -f config[content_type]=json \
  -f config[secret]="YOUR_SECRET" \
  -f events[]=pull_request \
  -f events[]=issues

Events נפוצים:

• push — מישהו דחף קוד ל-branch
• pull_request — PR נפתח, נסגר, מתמזג, או מקבל עדכון
• issues — issue נפתח, נסגר, מתויג
• release — release חדש פורסם
• deployment — deployment התחיל או הסתיים
• workflow_run — Actions workflow התחיל או סיים
• check_run / check_suite — בדיקות CI עודכנו

כל event כולל שדה action שמפרט מה בדיוק קרה. למשל, pull_request עם action: "opened", "closed", "synchronize" (קוד חדש נדחף ל-PR קיים), "review_requested". זה חשוב כי בדרך כלל לא רוצים לטפל בכל ה-actions — רק בספציפיים. למשל, בוט שמוסיף labels צריך רק opened, לא synchronize.

מבנה ה-Payload — מה מגיע בפועל:

כל payload כולל שלושה חלקים עיקריים:

• action — מה קרה: "opened", "closed", "created", "deleted"
• אובייקט האירוע — ה-PR עצמו, ה-issue, ה-release — עם כל הפרטים שלו
• repository — באיזה ריפו קרה. כולל שם, owner, URL, visibility
• sender — מי גרם לאירוע. כולל login, avatar URL, type (User/Bot)
• installation — אם ה-webhook שייך ל-GitHub App, כולל את ה-installation ID

ה-payload עשוי להיות גדול — עד 25MB. לכן חשוב לפרסר רק את השדות שצריכים ולא לנסות לשמור את כל ה-payload.

דוגמאות מייצגות — תרחישי Webhook בסטארטאפים ישראליים:

הדוגמאות הבאות מבוססות על תבניות שימוש נפוצות ומייצגות סיטואציות טיפוסיות.

Webhooks הם כלי קריטי בסטארטאפים ישראליים שצריכים לנוע מהר עם צוותים קטנים. הנה חמישה תרחישים טיפוסיים:

תרחיש 1 — התראות Slack אוטומטיות (צוות של 15 מפתחים):

סטארטאפ B2B SaaS מגדיר webhook על pull_request.opened ו-pull_request.review_requested. כל PR חדש שולח הודעה מפורמטת ל-Slack channel של הצוות עם שם ה-PR, מי פתח, כמה קבצים שונו, וקישור ישיר ל-review. כש-review מתבקש, ה-reviewer מקבל DM אישי. התוצאה: זמן ה-review ירד מ-24 שעות ל-4 שעות כי המידע מגיע מיידית ולא צריך לבדוק GitHub באופן ידני.

תרחיש 2 — סנכרון GitHub-Jira דו-כיווני:

חברת cybersecurity ישראלית עם צוותי פיתוח ו-product שמשתמשים בכלים שונים. Webhook על event issues מאפשר: כל issue שנסגר ב-GitHub מעדכן אוטומטית את הכרטיס המתאים ב-Jira ל-"Done". כשמוסיפים label priority:critical ב-GitHub, ה-Jira ticket עולה ל-P1. חיסכון: 30 דקות ביום של עדכונים ידניים, ואין סיכון ששני הכלים לא מסונכרנים.

תרחיש 3 — בוט Quality Gate עם auto-labeling:

צוות DevOps בסטארטאפ fintech מגדיר webhook על check_suite.completed. כש-CI נכשל, הבוט מוסיף label ci-failed ל-PR, שולח DM ל-author ב-Slack, ומסיר את ה-PR מ-"Ready for Review" ב-Project board. כש-CI עובר, הבוט מסיר ci-failed, מוסיף ready-for-review, ומקצה reviewer אוטומטית על בסיס CODEOWNERS.

תרחיש 4 — Release Notes אוטומטיים:

כל release.published מפעיל webhook שלוקח את ה-release notes מ-GitHub, מפרמט אותם ל-HTML, שולח email ל-רשימת לקוחות, ומפרסם לדף עדכונים פנימי. ה-PM לא צריך לכתוב changelog ידנית — הכל מגיע אוטומטית מ-GitHub releases.

תרחיש 5 — Deployment Tracking ו-Compliance:

סטארטאפ healthtech שכפוף לרגולציה מגדיר webhook על deployment ו-deployment_status. כל deployment נרשם למערכת audit פנימית עם: מי ביצע, מה השתנה (commit SHA), מתי, והאם ה-deployment הצליח. זה מספק את דרישות ה-compliance של SOC2 ו-HIPAA בלי עבודה ידנית.

כל התרחישים האלה משותפים בדבר אחד: הם הופכים תהליך ידני לאוטומטי. במקום שמישהו יבדוק, יעדכן, וישלח — webhook מפעיל תהליך מיידי. בסטארטאפ ישראלי ממוצע, אוטומציה אחת כזו חוסכת 2-5 שעות שבועיות של עבודה ידנית לצוות.

8.7 אבטחת Webhooks — אימות חתימות

הבעיה: כל מי שיודע את ה-URL שלכם יכול לשלוח POST מזויף שנראה כמו GitHub. בלי אימות, אי אפשר לדעת שה-webhook באמת הגיע מ-GitHub. תוקף יכול לגרום לבוט שלכם למזג PRs, למחוק branches, או לשלוח הודעות בשם הארגון.

הפתרון: HMAC-SHA256 signature verification. כשמגדירים webhook, בוחרים secret. GitHub משתמש ב-secret כדי ליצור חתימה על כל payload, ושולח אותה ב-header X-Hub-Signature-256. השרת שלכם מחשב את אותה חתימה ומשווה.

קוד אימות ב-Node.js:

import crypto from 'crypto';

function verifyWebhookSignature(payload, signature, secret) {
  const expected = 'sha256=' + crypto
    .createHmac('sha256', secret)
    .update(payload, 'utf-8')
    .digest('hex');

  // CRITICAL: use timingSafeEqual to prevent timing attacks
  // NEVER use === for signature comparison
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

// In your Express handler:
app.post('/webhook', (req, res) => {
  const signature = req.headers['x-hub-signature-256'];
  const event = req.headers['x-github-event'];
  const deliveryId = req.headers['x-github-delivery'];

  if (!verifyWebhookSignature(req.rawBody, signature, process.env.WEBHOOK_SECRET)) {
    console.warn(`Rejected webhook ${deliveryId}: invalid signature`);
    return res.status(401).send('Invalid signature');
  }

  // Signature verified — safe to process
  console.log(`Event: ${event}, Action: ${req.body.action}, Delivery: ${deliveryId}`);

  // Respond immediately, process async
  res.status(200).send('OK');

  // Queue async processing (don't block the response)
  processWebhookAsync(event, req.body);
});

נקודות קריטיות:

• crypto.timingSafeEqual() — לא ===. השוואה רגילה פגיעה ל-timing attacks שחושפים את ה-secret בית אחרי בית. timingSafeEqual לוקחת אותו זמן בלי קשר לכמה בתים מתאימים.
• שמרו את ה-secret ב-environment variable — לא בקוד, לא ב-config file שמתקמפל לתוך ה-image.
• הגיבו 2XX תוך 10 שניות — עיבוד כבד עשו async בתור (queue). Redis, SQS, או אפילו setTimeout פשוט.
• סובבו (rotate) את ה-secret מדי פעם — GitHub מאפשר להגדיר secret חדש לפני שמוחקים את הישן.
• Idempotency — GitHub עלול לשלוח את אותו webhook פעמיים (re-delivery). שמרו את X-GitHub-Delivery (GUID ייחודי לכל delivery) ובדקו שלא עיבדתם אותו כבר. שימרו את ה-IDs ב-Redis או בזיכרון (עם TTL) ודחו deliveries כפולים.

IP Allowlisting — שכבת הגנה נוספת:

מעבר לחתימה, אפשר להגביל את ה-webhook endpoint לקבל בקשות רק מכתובות IP של GitHub:

# שליפת רשימת כתובות IP של GitHub
gh api /meta --jq '.hooks'
# ["192.30.252.0/22", "185.199.108.0/22", ...]

הוסיפו את הרשימה ל-firewall או ל-reverse proxy (Nginx, Cloudflare, AWS ALB). שימו לב: הרשימה עלולה להשתנות כש-GitHub מוסיפה data centers, אז כדאי ליצור סקריפט שמושך את הרשימה אחת ליום ומעדכן את ה-allowlist אוטומטית. שילוב של IP allowlisting עם HMAC signature verification נותן שתי שכבות הגנה — גם אם אחת נכשלת, השנייה מגנה.

// server.js — minimal webhook handler
import http from 'http';
import crypto from 'crypto';

const SECRET = process.env.WEBHOOK_SECRET || 'dev-secret';
const PORT = 3000;
const processed = new Set(); // idempotency guard

function verify(payload, sig) {
  const expected = 'sha256=' + crypto.createHmac('sha256', SECRET)
    .update(payload).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));
}

http.createServer((req, res) => {
  if (req.method !== 'POST') { res.end('OK'); return; }

  let body = '';
  req.on('data', chunk => body += chunk);
  req.on('end', () => {
    const sig = req.headers['x-hub-signature-256'];
    const deliveryId = req.headers['x-github-delivery'];

    if (!sig || !verify(body, sig)) {
      res.writeHead(401); res.end('Bad signature');
      return;
    }

    // Idempotency check
    if (processed.has(deliveryId)) {
      res.writeHead(200); res.end('Already processed');
      return;
    }
    processed.add(deliveryId);

    const event = req.headers['x-github-event'];
    const data = JSON.parse(body);
    console.log(`[${event}] ${data.action} by ${data.sender?.login}`);

    if (event === 'pull_request' && data.action === 'opened') {
      console.log(`New PR: #${data.pull_request.number} "${data.pull_request.title}"`);
      console.log(`Author: ${data.pull_request.user.login}`);
      console.log(`Files changed: ${data.pull_request.changed_files}`);
      // Here you would call the API to add a comment, label, etc.
    }

    if (event === 'issues' && data.action === 'opened') {
      console.log(`New Issue: #${data.issue.number} "${data.issue.title}"`);
    }

    res.writeHead(200); res.end('OK');
  });
}).listen(PORT, () => console.log(`Webhook server on port ${PORT}`));

8.8 GitHub Apps — האינטגרציה המתקדמת

PATs הם סבבה לסקריפטים אישיים. אבל מה אם בונים בוט שצריך לעבוד על ריפוזיטורים של אנשים אחרים? או אינטגרציה שלא תלויה במשתמש ספציפי? GitHub Apps הם התשובה.

למה GitHub App ולא PAT:

• זהות עצמאית — App פועלת בשם עצמה, לא בשם משתמש. אם העובד עוזב — ה-App ממשיכה לעבוד.
• Tokens קצרי חיים — installation tokens תקפים שעה אחת. PAT תקף חודשים-שנים. אם token דולף, הנזק מוגבל.
• הרשאות מדויקות — לכל endpoint בנפרד: issues: write, contents: read.
• Rate limit גבוה — עד 15,000 בקשות/שעה (Enterprise Cloud). +50 לכל ריפו/משתמש מעל 20.
• Webhooks מובנים — ה-App מגדירה אילו events היא מקבלת. לא צריך להגדיר webhook בכל ריפו בנפרד.
• לא צורכת seat — לא נספרת כמשתמש בארגון. חשוב לארגונים גדולים שמשלמים per-seat.

יצירת GitHub App:

1. Settings → Developer settings → GitHub Apps → New GitHub App
2. הגדירו שם, Homepage URL, ו-Webhook URL (אם רוצים events)
3. בחרו Permissions — מה ה-App צריכה לעשות
4. בחרו Events — אילו webhooks לקבל
5. צרו private key — קובץ PEM שישמש לאימות

זרימת אימות — שלושה שלבים בקוד:

// Step 1: Generate JWT from private key
import jwt from 'jsonwebtoken';
import fs from 'fs';

const privateKey = fs.readFileSync('private-key.pem');
const payload = {
  iat: Math.floor(Date.now() / 1000) - 60,   // issued at (60s ago for clock drift)
  exp: Math.floor(Date.now() / 1000) + 600,   // expires in 10 minutes
  iss: APP_ID                                   // your GitHub App ID
};
const jwtToken = jwt.sign(payload, privateKey, { algorithm: 'RS256' });

// Step 2: Get installation ID
// gh api /app/installations --jq '.[0].id' -H "Authorization: Bearer JWT"

// Step 3: Exchange JWT for installation access token
const response = await fetch(
  `https://api.github.com/app/installations/${installationId}/access_tokens`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${jwtToken}`,
      Accept: 'application/vnd.github+json'
    }
  }
);
const { token } = await response.json();
// token is valid for 1 hour — use it for API calls

דרך קלה יותר — Manifest Flow:

במקום למלא טפסים ידנית, אפשר ליצור App מ-manifest JSON שמגדיר את כל ההרשאות, events, ו-webhook URL. ה-manifest flow הוא handshake דמוי OAuth שיוצר אוטומטית את ה-App registration, כולל webhook secret, private key, client secret, וה-App ID. שימושי לאוטומציה של יצירת Apps, ליצירת templates שצוותים שונים יכולים להשתמש בהם, וליצירת Apps דרך CI/CD.

מתי PAT ומתי GitHub App — סיכום מהיר:

• פרויקט אישי, סקריפט שרץ על המכונה שלכם? Fine-grained PAT — מהיר להגדרה, מספיק טוב.
• כלי שצוות משתמש בו? GitHub App — לא תלוי במשתמש ספציפי, tokens מתחדשים.
• שרת production שמטפל ב-webhooks? GitHub App — אימות מובנה, rate limit גבוה, audit trail ברור.
• CI/CD workflow? GITHUB_TOKEN — מובנה ב-Actions, לא צריך להגדיר כלום.

Probot — framework לפיתוח GitHub Apps ב-Node.js:

אם אתם בונים App ב-Node.js, Probot חוסך הרבה עבודה. במקום לנהל ידנית JWT generation, installation tokens, webhook verification, ו-event routing — Probot מטפל בכל זה אוטומטית. מתקינים, כותבים event handlers, ו-Probot עושה את השאר. זה ה-framework שמאחורי הרבה מה-GitHub Apps הפופולריות כמו Stale, Lock Threads, ו-Renovate:

// Using Probot framework
export default (app) => {
  // Respond to new PRs
  app.on('pull_request.opened', async (context) => {
    // context.octokit is already authenticated!
    const { data: files } = await context.octokit.pulls.listFiles(
      context.pullRequest({ per_page: 100 })
    );

    // Check if PR modifies sensitive files
    const sensitiveFiles = files.filter(f =>
      f.filename.includes('.env') || f.filename.includes('secrets')
    );

    if (sensitiveFiles.length > 0) {
      await context.octokit.issues.createComment(
        context.issue({
          body: '⚠️ This PR modifies sensitive files. Extra review required.'
        })
      );
      await context.octokit.issues.addLabels(
        context.issue({ labels: ['security-review'] })
      );
    } else {
      await context.octokit.issues.createComment(
        context.issue({ body: 'Thanks for the PR!' })
      );
    }
  });
};

# Replace YOUR_USERNAME with your GitHub username
gh api /users/{YOUR_USERNAME}/installation --jq '.id'

8.9 Octokit ו-gh api — כלי עבודה יומיים

אפשר לכתוב fetch() ידנית לכל קריאת API — אבל למה? Octokit הוא ה-SDK הרשמי של GitHub שמעטפת את כל ה-API עם TypeScript, auto-pagination, ניהול tokens, ועוד. זה מה שמפתחים מנוסים משתמשים ב-production.

התקנה ושימוש בסיסי:

npm install octokit

import { Octokit } from 'octokit';

// Authenticate with PAT
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

// REST: List issues
const { data: issues } = await octokit.rest.issues.listForRepo({
  owner: 'your-org',
  repo: 'your-repo',
  state: 'open',
  per_page: 10
});
console.log(issues.map(i => `#${i.number} ${i.title}`));

// GraphQL: Same but with nested data
const { repository } = await octokit.graphql(`{
  repository(owner: "your-org", name: "your-repo") {
    issues(first: 10, states: OPEN) {
      nodes {
        number
        title
        labels(first: 5) { nodes { name } }
      }
    }
  }
}`);
console.log(repository.issues.nodes);

Octokit ל-GitHub Apps:

import { App } from 'octokit';

const app = new App({
  appId: process.env.APP_ID,
  privateKey: process.env.PRIVATE_KEY,
});

// Get authenticated octokit for a specific installation
const octokit = await app.getInstallationOctokit(installationId);

// Now use it — token management is automatic!
// JWT generation, installation token exchange, token refresh — all handled
const { data } = await octokit.rest.pulls.list({
  owner: 'your-org',
  repo: 'your-repo',
  state: 'open'
});

Auto-pagination — בלי לנהל עמודים:

אחד הפיצ'רים החזקים ביותר של Octokit. במקום לנהל ידנית Link headers, עמודים, ולולאות — octokit.paginate() עושה את הכל:

// Instead of manually following Link headers...
const allIssues = await octokit.paginate(
  octokit.rest.issues.listForRepo,
  { owner: 'your-org', repo: 'your-repo', state: 'all', per_page: 100 }
);
console.log(`Total issues: ${allIssues.length}`);
// Octokit follows all pages automatically

// You can also use a map function to transform while paginating:
const titles = await octokit.paginate(
  octokit.rest.issues.listForRepo,
  { owner: 'your-org', repo: 'your-repo', per_page: 100 },
  (response) => response.data.map(issue => issue.title)
);
// titles is a flat array of all issue titles across all pages

חבילות Octokit עיקריות:

• octokit (v5.0.5) — all-batteries-included: REST + GraphQL + Apps + Webhooks
• @octokit/rest (v22.0.1) — REST API client בלבד — קל יותר אם לא צריכים GraphQL
• @octokit/graphql — GraphQL client בלבד
• @octokit/app — GitHub App utilities (JWT, installation tokens)
• @octokit/webhooks — Webhook verification and handling

Webhook Verification עם Octokit:

החבילה @octokit/webhooks מפשטת את כל תהליך האימות והטיפול ב-webhooks:

import { Webhooks } from '@octokit/webhooks';

const webhooks = new Webhooks({
  secret: process.env.WEBHOOK_SECRET
});

// Type-safe event handlers
webhooks.on('pull_request.opened', async ({ payload }) => {
  console.log(`PR #${payload.pull_request.number}: ${payload.pull_request.title}`);
  console.log(`By: ${payload.pull_request.user.login}`);
  console.log(`Changed files: ${payload.pull_request.changed_files}`);
});

webhooks.on('issues.labeled', async ({ payload }) => {
  if (payload.label.name === 'urgent') {
    console.log(`Issue #${payload.issue.number} marked as urgent!`);
  }
});

// In Express:
app.post('/webhook', async (req, res) => {
  await webhooks.verifyAndReceive({
    id: req.headers['x-github-delivery'],
    name: req.headers['x-github-event'],
    signature: req.headers['x-hub-signature-256'],
    payload: JSON.stringify(req.body),
  });
  res.status(200).send('OK');
});

מתי Octokit, מתי gh api, מתי curl:

• Octokit — אפליקציות Node.js, GitHub Apps, כל דבר שרץ בקוד production. TypeScript types, auto-pagination, ניהול tokens אוטומטי, webhook verification מובנית.
• gh api — סקריפטים מהירים, בדיקות, one-off tasks מהטרמינל. מהיר, pre-authenticated, ו-JQ filtering. מושלם ל-cron jobs ו-bash scripts.
• curl — debugging כשצריכים לראות raw headers/response, או בסביבות מינימליות בלי gh/Node.js. גם שימושי ב-CI environments שאין בהם gh מותקן.

mkdir gh-api-test && cd gh-api-test
npm init -y && npm install octokit

# Create script.js:
cat > script.js << 'EOF'
import { Octokit } from 'octokit';
const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });
const { data: user } = await octokit.rest.users.getAuthenticated();
console.log(`Hello ${user.login}! You have ${user.public_repos} public repos.`);
EOF

# Add "type": "module" to package.json, then:
GITHUB_TOKEN=$(gh auth token) node script.js

import { Octokit } from 'octokit';

const octokit = new Octokit({ auth: process.env.GITHUB_TOKEN });

// Get all your repos (auto-pagination!)
const repos = await octokit.paginate(octokit.rest.repos.listForAuthenticatedUser, {
  sort: 'updated',
  per_page: 100
});

// Summary: name, stars, language, open issues
console.log(`Total repos: ${repos.length}\n`);
console.log('--- Top 20 Most Recently Updated ---');
repos.slice(0, 20).forEach(r => {
  console.log(`${r.name.padEnd(30)} | ${r.language || 'N/A'} | ${r.open_issues_count} issues | ${r.stargazers_count} stars`);
});

// Find repos with problems
const noDesc = repos.filter(r => !r.description);
const noLicense = repos.filter(r => !r.license && r.visibility === 'public');
const archived = repos.filter(r => r.archived);

console.log(`\n--- Health Check ---`);
if (noDesc.length > 0) {
  console.log(`${noDesc.length} repos without description:`);
  noDesc.forEach(r => console.log(`  - ${r.name}`));
}
if (noLicense.length > 0) {
  console.log(`${noLicense.length} public repos without license:`);
  noLicense.forEach(r => console.log(`  - ${r.name}`));
}
console.log(`${archived.length} archived repos`);
console.log(`${repos.filter(r => r.open_issues_count > 10).length} repos with 10+ open issues`);

8.10 Rate Limits — הגבולות שחייבים להכיר

ל-GitHub API יש מגבלות. התעלמו מהן — ותקבלו 403 Forbidden עם ההודעה API rate limit exceeded. בואו נכיר את כל המספרים ואת האסטרטגיות להתמודד איתם.

Primary Rate Limits (בקשות/שעה):

• לא מאומת: 60 בקשות/שעה — כמעט חסר שימוש
• PAT (fine-grained/classic): 5,000 בקשות/שעה
• GitHub App (standard): 5,000 בקשות/שעה
• GitHub App (Enterprise Cloud): 15,000 בקשות/שעה
• GITHUB_TOKEN ב-Actions: 1,000 בקשות/שעה (לכל ריפו)

GitHub App scaling: אם ל-App יש יותר מ-20 ריפוזיטורים או 20 משתמשים, היא מקבלת 50 בקשות נוספות/שעה לכל ריפו/משתמש, עד תקרה של 12,500 בקשות נוספות. בפועל, App גדולה עם 200 ריפוזיטורים ב-Enterprise Cloud מקבלת: 15,000 (base) + (200-20) * 50 = 24,000 בקשות/שעה. זה הרבה מאוד — מספיק לרוב האוטומציות.

מה קורה כשנגמר ה-rate limit?

כשמגיעים ל-primary rate limit, ה-API מחזיר 403 Forbidden עם header X-RateLimit-Remaining: 0. ה-header X-RateLimit-Reset מכיל Unix timestamp שאומר מתי ה-limit יתאפס (בדרך כלל תוך פחות מ-60 דקות). כש-secondary rate limit מכה, מקבלים 429 Too Many Requests עם header Retry-After שאומר כמה שניות לחכות.

Secondary Rate Limits — מגבלות נוספות מעבר ל-primary:

• מקסימום 100 בקשות מקביליות (concurrent)
• מקסימום 900 points/דקה לכל endpoint
• מקסימום 80 בקשות יצירת תוכן/דקה (POST שיוצרים issues, comments, PRs)
• מקסימום 90 שניות CPU לכל 60 שניות real time

Response Headers — איך לדעת איפה אתם עומדים:

# בדיקת rate limit headers מכל response
gh api repos/{owner}/{repo}/issues -i 2>&1 | grep -i "x-ratelimit"
# X-RateLimit-Limit: 5000
# X-RateLimit-Remaining: 4985
# X-RateLimit-Reset: 1712163600
# X-RateLimit-Used: 15
# X-RateLimit-Resource: core

Conditional Requests — הנשק הסודי:

כל response כולל header ETag. שמרו אותו. בקריאה הבאה, שלחו אותו ב-If-None-Match:

# First request — save the ETag
ETAG=$(gh api repos/{owner}/{repo}/issues -i 2>&1 | grep -i "^etag:" | awk '{print $2}' | tr -d '\r')

# Subsequent requests — use conditional
gh api repos/{owner}/{repo}/issues -H "If-None-Match: ${ETAG}" -i 2>&1 | head -1
# If nothing changed: HTTP/2 304 (0 bytes, does NOT count against rate limit!)
# If changed: HTTP/2 200 with new data + new ETag

למה זה חשוב? כי 304 responses לא נספרות כלל ב-rate limit. אם עושים polling כל 30 שניות ורוב הזמן אין שינוי — conditional requests חוסכים 90%+ מהקריאות.

אסטרטגיות לניהול rate limits:

• Conditional requests — 304 responses לא נספרות. השתמשו תמיד ל-polling.
• GraphQL במקום REST — קריאה אחת במקום 10 = חיסכון 90%.
• Pagination מושכלת — בקשו per_page=100 (המקסימום) כדי למזער קריאות.
• Caching בצד שלכם — שמרו results ב-cache (Redis, in-memory), רעננו רק מה שצריך.
• Exponential backoff — קיבלתם 429? חכו שנייה, אז שתיים, אז ארבע. לעולם לא retry מיידי.
• בדקו לפני שקוראים — GET /rate_limit מראה כמה נשאר (והקריאה עצמה לא נספרת!).

Exponential Backoff בקוד — חובה לכל אוטומציה:

Exponential backoff אומר: קיבלתם 429 (Too Many Requests)? חכו שנייה. עדיין 429? חכו שתיים. עדיין? ארבע. הזמן מכפיל את עצמו. זה מונע "thundering herd" — מצב שבו כל הלקוחות מנסים שוב באותו רגע ומעמיסים על ה-API עוד יותר.

async function apiCallWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status === 429 || error.status === 403) {
        const retryAfter = error.response?.headers['retry-after'];
        const waitTime = retryAfter
          ? parseInt(retryAfter) * 1000
          : Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        console.log(`Rate limited. Waiting ${waitTime}ms...`);
        await new Promise(r => setTimeout(r, waitTime));
      } else {
        throw error; // Non-rate-limit error
      }
    }
  }
  throw new Error('Max retries exceeded');
}

כמה rate limit עולה לכם כל שיטה?

בואו נשווה את העלות בבקשות של אותה פעולה בשלוש גישות:

המסקנה: GraphQL חוסך rate limit משמעותי על שליפות מורכבות עם nested data, אבל ל-REST יש יתרון ברור ב-polling ובמעקב שוטף בזכות conditional requests (304 לא נספר ב-rate limit כלל).

gh api /rate_limit --jq '.resources | to_entries[] | "\(.key): \(.value.remaining)/\(.value.limit)"'

8.11 סיכום ומבט קדימה

gh api /user --jq '.login'