DevOps والتشغيل الأدلة التقنية

أول مستودع Git لك: من git init إلى أول push على Gitea

خطوة بخطوة من مجلد مشروع على جهازك إلى مستودع على Gitea، مع مفاتيح SSH ورموز الوصول والأخطاء التي سوف تراها في أول مرة وكيف تقرؤها.

أول مستودع Git لك: من git init إلى أول push على Gitea

إذا كان مشروعك اليوم مجلداً على جهازك اسمه مثل invoice-tool-final-v2، وتحفظ نسخته الاحتياطية بأن تضغطه وترسله لنفسك بالبريد، ويطلب منك زميل أو مشرف أن «ترفعه على Git»، فأنت في الموقف الذي يبدأ منه أغلب المطورين. وقد تقرأ شرحاً يقول نفذ git init ثم git push، فتنفذ الأمرين ويظهر لك خطأ لا تفهمه مثل src refspec main does not match any أو Permission denied (publickey)، وتجد نفسك تنسخ أوامر من منتديات لا تعرف ماذا تفعل.

وفي إدارة النسخ وGit للمبتدئين شرحنا لماذا نحتاج Git وكيف يعمل من الداخل: المناطق الثلاث وال Commit والفروع والمستودع البعيد. وفي هذا المقال نأخذ الجانب العملي الذي يأتي بعد الفهم: مجلد حقيقي على جهازك يصبح مستودعاً على منصة استضافة كود، وهي هنا Gitea على جهازك، والخطوات نفسها تعمل مع GitHub وGitLab مع اختلاف بسيط في الواجهة. وسوف نمر بكل خطأ يظهر لمن يفعلها أول مرة، لأننا رأيناها فعلاً أثناء التجربة، ونشرح كيف تقرأ كل واحد منها. وسوف نناقش في هذا المقال ما يلي:

  • لماذا تحتاج منصة استضافة كود Code Hosting، وما الفرق بين المستودع على جهازك والمستودع على السيرفر.
  • تجهيز هويتك في Git، وإنشاء المستودع على Gitea، وتحويل المجلد إلى مستودع محلي مع ملف .gitignore صحيح من أول يوم.
  • أول Commit، ثم أول خطأ: الدفع قبل أن يوجد ما يدفع.
  • الاتصال عبر SSH: التحقق من بصمة السيرفر، ومفتاح من نوع Ed25519، والخطأ Permission denied (publickey).
  • البديل عبر HTTPS برمز وصول Access Token بدلاً من الباسورد، وأين يحفظه Git.
  • جهاز ثان يستنسخ ويعدل ويدفع، ثم ماذا يحدث إذا دفعت سراً بالخطأ، وماذا يحدث إذا دفعت إلى مستودع غير موجود.

لماذا تحتاج منصة استضافة الكود؟ Code Hosting

Git نفسه لا يحتاج إلى سيرفر، فالأمر git init ينشئ مستودعاً كاملاً بتاريخه على جهازك، وتستطيع أن تعمل عليه سنوات دون أن يعرف أحد. ولكن المستودع الذي على جهاز واحد له ثلاث مشاكل: إذا تعطل القرص ضاع المشروع وتاريخه معه، ولا يستطيع زميلك أن يعمل معك إلا إذا أرسلت له نسخة ثم دمجت عمله يدوياً، ولا يوجد مكان يرى فيه أحد الكود دون أن يطلبه منك. ولذلك يحتاج كل مشروع حقيقي إلى نسخة مشتركة من المستودع على سيرفر، يدفع إليها الجميع ويجلبون منها، وتسمى المستودع البعيد Remote.

ومنصة استضافة الكود Code Hosting Platform هي البرنامج الذي يحفظ هذه المستودعات ويضيف حولها ما يحتاجه الفريق: حسابات وصلاحيات، وواجهة ويب تعرض الكود والتاريخ، وطلبات الدمج Pull Requests ومراجعة الكود، والمهام Issues، وخطوط CI/CD. وأشهرها GitHub وGitLab وBitbucket كخدمات مستضافة، وGitea وForgejo وGitLab كبرامج تثبتها على سيرفرك. وفي هذا المسار نستخدم Gitea لأنه خفيف ويعمل في Container واحد، وقد شرحنا تثبيته للإنتاج مع النطاق والشهادة والنسخ الاحتياطي في تثبيت Gitea مع Docker Compose، أما هنا فنشغله على جهازك للتجربة فقط.

أين تستضيف مستودعك؟ Choosing a Host

قبل الخطوات نقف قليلاً عند السؤال الذي يسأله كل من يبدأ: هل أضع المشروع على GitHub أم على سيرفر Gitea خاص؟ والإجابة تعتمد على ثلاثة أشياء: من يملك الكود، وأين يجب أن تبقى البيانات، ومن سوف يعمل عليه. فإذا كان المشروع شخصياً أو مفتوح المصدر وتريد أن يراه الناس ويساهموا فيه، فالمنصات المستضافة مثل GitHub وGitLab.com هي المكان الطبيعي، لأن المساهمين لديهم حسابات هناك أصلاً، ولأنك لا تدير سيرفراً ولا نسخاً احتياطية. أما إذا كان الكود لجهة تشترط أن تبقى بياناتها داخل شبكتها أو داخل المملكة، أو كان فيه ما لا يجب أن يغادر الشركة، أو كان الفريق يريد خطوط CI تعمل على سيرفراته، فالسيرفر الخاص مثل Gitea أو GitLab المثبت ذاتياً هو الأنسب، ومعه تتحمل مسؤولية التحديث والنسخ الاحتياطي والمراقبة.

والجميل في Git أن هذا القرار ليس نهائياً، فالمستودع ينتقل بين المنصات كاملاً بتاريخه بأمر git push إلى رابط جديد، وGitea يملك صفحة Migrate Repository تنقل من GitHub والمنصات الأخرى المستودع مع المهام وطلبات الدمج. وما ينتقل بصعوبة هو ما حول الكود: ملفات CI المكتوبة لمنصة بعينها، والصلاحيات، والروابط في التوثيق، ولذلك اكتب خطواتك بطريقة لا تعتمد على منصة واحدة أكثر مما تحتاج. والأوامر في هذا المقال هي نفسها في كل المنصات، والفرق فقط في مكان الأزرار في الواجهة.

والصورة التالية تبين الخطوات الخمس التي سوف نمر بها، ولاحظ أن أربعاً منها تحدث على جهازك فقط:

على اليمين جهازك Local وفيه مجلد المشروع invoice.py وREADME.md مع الخطوة 1 git init، ثم سهم git add إلى منطقة التجهيز Staging Area، ثم سهم git commit إلى المستودع المحلي .git، ثم سهم أخضر 5 git push إلى سيرفر Gitea على اليسار وفيه المستودع البعيد Remote dev1/invoice-tool، وعلى السهم 4 git remote add، وفي الأسفل كل شيء قبل git push يحدث على جهازك فقط
الأوامر بالترتيب، والسيرفر لا يعرف شيئاً عن عملك حتى تدفع

تجهيز المختبر Lab Setup

سوف نستخدم ثلاثة Containers على شبكة Docker واحدة: سيرفر Gitea، وContainer اسمه dvb-laptop يمثل جهازك، وآخر اسمه dvb-laptop2 يمثل جهاز زميلك، وكلاهما Alpine صغير نثبت فيه git وعميل SSH. وإذا كان Git مثبتاً على جهازك فتستطيع أن تنفذ أوامر «جهازك» عليه مباشرة بدلاً من الـ Container، وأي شيء يخص Windows أو macOS سوف ننبه عليه في مكانه.

docker network create dvb-net

docker run -d --name dvb-gitea --network dvb-net -p 3471:3000 \
  -e GITEA__security__INSTALL_LOCK=true \
  -e GITEA__server__ROOT_URL=http://localhost:3471/ \
  -e GITEA__server__SSH_DOMAIN=dvb-gitea \
  -e GITEA__database__DB_TYPE=sqlite3 \
  -e GITEA__service__DISABLE_REGISTRATION=true \
  -v dvb-gitea-data:/data gitea/gitea:28.3.0

docker exec -u git dvb-gitea gitea admin user create --admin \
  --username dev1 --password 'Lab-Pass-2026!' --email [email protected] \
  --must-change-password=false

for m in laptop laptop2; do
  docker run -d --name dvb-$m --network dvb-net alpine:3.24 sleep infinity
  docker exec dvb-$m apk add --no-cache git openssh-client curl
done
docker exec dvb-laptop sh -c 'git --version; ssh -V'

والمخرج سوف يكون كما يلي:

New user 'dev1' has been successfully created!
git version 2.54.0
OpenSSH_10.3p1, OpenSSL 3.5.9 29 Sep 2026

في الإعداد أعلاه لاحظ التالي:

  • صورة Gitea الرسمية فيها سيرفر SSH داخلي يعمل على المنفذ 22 داخل الـ Container، والمتغير SSH_DOMAIN هو الاسم الذي يكتبه Gitea في روابط الاستنساخ، فجعلناه اسم الـ Container لأن «الجهازين» يصلان إليه بهذا الاسم داخل الشبكة.
  • أطفأنا التسجيل المفتوح DISABLE_REGISTRATION وأنشأنا الحساب من سطر الأوامر، وهذا ما ننصح به في أي Gitea داخلي، والسبب أن التسجيل المفتوح يسمح لأي شخص يصل إلى الصفحة بإنشاء حساب ومستودعات على سيرفرك.
  • الواجهة متاحة من متصفحك على http://localhost:3471، وكل ما نفعله فيها في هذا المقال تستطيع فعله من الواجهة البرمجية API أيضاً.

قبل أول أمر: هويتك في Git Identity

كل Commit يحمل اسم كاتبه وبريده، وGit يأخذهما من الإعداد، فإذا لم تضبطهما رفض أن ينشئ Commit أو أخذ اسماً من اسم الجهاز لا يعني شيئاً لزملائك. ولذلك فأول ما تفعله على أي جهاز جديد هو ثلاثة أوامر:

git config --global user.name "Dev One"
git config --global user.email [email protected]
git config --global init.defaultBranch main
git config --global --list

والمخرج سوف يكون كما يلي:

user.name=Dev One
[email protected]
init.defaultbranch=main

في الإعداد أعلاه لاحظ التالي:

  • الخيار --global يحفظ القيمة في الملف ~/.gitconfig لكل مستودعاتك على هذا الجهاز، وتستطيع أن تغيرها لمستودع واحد بنفس الأمر دون --global من داخله، وهذا مفيد إذا كان عندك بريد للعمل وآخر لمشاريعك الشخصية، والترتيب الكامل للملفات في توثيق git config.
  • استخدم البريد نفسه المسجل في حسابك على المنصة، والسبب أن Gitea وGitHub يربطان كل Commit بالحساب عن طريق البريد، فإذا اختلف ظهر ال Commit باسم غريب دون صورة الحساب ولم يحسب لك.
  • الإعداد init.defaultBranch يحدد اسم الفرع الأول في كل مستودع جديد، وGit ما زال يستخدم master افتراضياً ويطبع تنبيهاً بذلك، أما Gitea وGitHub وGitLab فتنشئ مستودعاتها بالفرع main، فإذا اختلف الاسمان بين جهازك والسيرفر فسوف تدفع فرعاً باسم غير الذي تتوقعه المنصة، ولذلك نضبطه مرة واحدة.

إنشاء المستودع على Gitea New Repository

سجل الدخول بالحساب dev1، ثم اضغط علامة + في الأعلى واختر New Repository، واكتب اسم المستودع ووصفاً قصيراً:

صفحة New Repository في Gitea: المالك Owner هو dev1، واسم المستودع Repository Name هو invoice-tool، وخيار Make repository private غير محدد، والوصف Small invoice calculator، وحقول Template وIssue Labels و.gitignore وLicense فارغة، وREADME بالقيمة Default
نموذج المستودع الجديد، والحقول الأخيرة نتركها فارغة عمداً

وفي هذا النموذج ثلاثة قرارات تستحق التوقف:

  • الخصوصية Visibility: المستودع العام Public يراه ويستنسخه كل من يصل إلى السيرفر دون حساب، والخاص Private يراه المالك ومن تعطيه صلاحية فقط. وفي المختبر تركناه عاماً لكي نجرب الاستنساخ دون حساب، أما مشروعك الحقيقي فاجعله خاصاً ما لم تقصد نشره، والسبب أن جعل المستودع العام خاصاً لاحقاً لا يسترجع ما استنسخه الناس قبل ذلك، كما سوف ترى في حادثة Toyota بعد قليل.
  • ملفات البداية: النموذج يعرض أن ينشئ ملف .gitignore من قالب، وملف ترخيص License، وملف README. وإذا كان عندك مجلد فيه كود تريد رفعه فاترك هذه كلها فارغة، والسبب أن المنصة سوف تنشئ Commit أول على السيرفر، وعندك على جهازك Commit أول مختلف، فيصبح المستودعان بتاريخين لا علاقة بينهما، ويرفض السيرفر دفعتك برسالة rejected (fetch first) وتحتاج إلى دمج تاريخين قبل أن تبدأ. أما إذا كنت تبدأ مشروعاً من الصفر فاطلبها من المنصة ثم استنسخ المستودع.
  • الاسم: استخدم حروفاً إنجليزية صغيرة وشرطة بين الكلمات، لأن الاسم يصبح جزءاً من الرابط ومن مسارات أخرى مثل أسماء ال Docker Images في ال Registry، وهذه لا تقبل الحروف الكبيرة.

وبعد الضغط على Create Repository يعرض Gitea صفحة المستودع الفارغ، وفيها رابطا الاستنساخ عبر HTTP وSSH، ومجموعتا أوامر جاهزة:

صفحة المستودع الفارغ dev1/invoice-tool في Gitea بعنوان Quick Guide، وفيها زرا New File وUpload File، واختيار HTTP أو SSH مع الرابط http://localhost:3471/dev1/invoice-tool.git، ثم قسم Creating a new repository on the command line وفيه touch README.md وgit init وgit checkout -b main وgit add وgit commit وgit remote add origin وgit push -u origin main، ثم قسم Pushing an existing repository from the command line وفيه git remote add origin وgit push -u origin main
المستودع الفارغ مع الأوامر التي تقترحها المنصة

لاحظ أن المجموعة الأولى تبدأ مستودعاً جديداً، والثانية لمستودع موجود على جهازك، وهي حالتنا، ولكننا لن ننسخها كما هي، وإنما نمر بكل خطوة ونفهم ما تفعله.

تحويل المجلد إلى مستودع محلي git init

على جهازك مجلد المشروع، وفيه سكربت Python صغير يحسب مجموع الفاتورة مع ضريبة القيمة المضافة 15%، وفيه أيضاً ما يوجد في أغلب المجلدات الحقيقية: ملف .env فيه باسورد قاعدة البيانات، ومجلد __pycache__ أنشأه Python عند التشغيل:

VAT = 0.15

def total(items):
    subtotal = sum(price * qty for price, qty in items)
    return round(subtotal * (1 + VAT), 2)

if __name__ == "__main__":
    print(total([(100, 2), (50, 1)]))

ندخل إلى المجلد ونحوله إلى مستودع، ثم نسأل Git عن الحالة:

cd /home/invoice-tool
git init
git status

والمخرج سوف يكون كما يلي:

Initialized empty Git repository in /home/invoice-tool/.git/

On branch main

No commits yet

Untracked files:
  (use "git add <file>..." to include in what will be committed)
	.env
	__pycache__/
	invoice.py

nothing added to commit but untracked files present (use "git add" to track)

الأمر git init لم يغير ملفاتك، وإنما أنشأ مجلداً مخفياً اسمه .git فيه قاعدة بيانات المستودع كلها: ال Commits والفروع والإعداد، ولذلك فإذا حذفت هذا المجلد رجع مشروعك مجلداً عادياً دون تاريخ، والتفاصيل في توثيق git init. ولاحظ أن الفرع اسمه main بسبب الإعداد الذي ضبطناه، وأن Git يرى ثلاثة أشياء غير متتبعة Untracked، اثنان منها لا يجب أن تدخل المستودع أبداً.

ملفات لا تدخل المستودع .gitignore

الملف .env فيه سر، ومجلد __pycache__ مخرجات يولدها Python من الكود ويختلف محتواها بين الأجهزة، ولو أضفتهما لدخل السر في التاريخ إلى الأبد، ولظهر لكل زميل تعديل في ملفات لم يلمسها. والحل ملف اسمه .gitignore في المجلد الرئيسي للمستودع، كل سطر فيه نمط Pattern لملفات يتجاهلها Git:

.env
__pycache__/
*.pyc

ومعه نضيف ملف README.md يشرح المشروع، وملف .env.example فيه أسماء المتغيرات دون قيمها، حتى يعرف من يستنسخ المشروع ماذا يحتاج أن يضبط:

DB_PASSWORD=

الآن نسأل عن الحالة بالصيغة المختصرة:

git status --short
?? .env.example
?? .gitignore
?? README.md
?? invoice.py

اختفى .env و__pycache__ من القائمة، والعلامة ?? تعني ملفاً غير متتبع. ولكل لغة قالب جاهز فيه ما تولده أدواتها عادة، وأشهر مجموعة لهذه القوالب مستودع github/gitignore، وهي نفسها التي يعرضها Gitea في نموذج المستودع الجديد، وقواعد الأنماط مثل / في آخر الاسم و* و! للاستثناء مشروحة في توثيق gitignore.

⚠️
الملف .gitignore يمنع الملفات غير المتتبعة فقط، فإذا كان الملف قد دخل في Commit سابق فإضافته إلى .gitignore لا تخرجه من المستودع، ولذلك أنشئ .gitignore قبل أول git add وليس بعده.

أول Commit First Commit

نضيف كل الملفات إلى منطقة التجهيز Staging Area ونراجع ما أضفناه قبل أن ننشئ ال Commit:

git add .
git status --short
git commit -m "Add invoice calculator with VAT"
git log --oneline

والمخرج سوف يكون كما يلي:

A  .env.example
A  .gitignore
A  README.md
A  invoice.py

[main (root-commit) 13ec719] Add invoice calculator with VAT
 4 files changed, 17 insertions(+)
 create mode 100644 .env.example
 create mode 100644 .gitignore
 create mode 100644 README.md
 create mode 100644 invoice.py

13ec719 Add invoice calculator with VAT

في المخرج أعلاه لاحظ التالي:

  • العلامة A تعني أن الملف أضيف إلى منطقة التجهيز، وهذه آخر فرصة لتنظر في القائمة وتتأكد أن لا شيء فيها لا يجب أن يكون، ولذلك اجعل git status عادة قبل كل Commit، خاصة مع git add . الذي يضيف كل ما يراه.
  • عبارة root-commit تعني أن هذا أول Commit في المستودع، أي أنه لا يملك أباً، و13ec719 هو أول سبعة أحرف من هاش ال Commit الذي يميزه.
  • الرسالة جملة قصيرة بصيغة الأمر تقول ما يفعله التغيير، وقد شرحنا قواعدها في رسالة ال Commit.

الخطأ الأول: src refspec main does not match any

في التجربة نفذنا الأوامر بالترتيب الذي ينفذه كثير من المبتدئين، أي أننا ربطنا المستودع البعيد ودفعنا مباشرة بعد git init وقبل أي Commit، فظهر هذا الخطأ:

error: src refspec main does not match any
error: failed to push some refs to 'dvb-gitea:dev1/invoice-tool.git'

والرسالة تبدو غامضة، ولكن معناها بسيط: طلبت من Git أن يدفع الفرع main، وهذا الفرع غير موجود بعد، والسبب أن الفرع في Git مؤشر Pointer على Commit، ولا يوجد أي Commit حتى الآن، فالفرع اسم دون شيء يشير إليه، وكلمة refspec هي الصيغة التي تحدد ما يدفع وإلى أين، كما في توثيق git push. والحل أن تنشئ Commit أولاً كما فعلنا في القسم السابق، وتظهر الرسالة نفسها أيضاً إذا كان فرعك المحلي اسمه master وطلبت دفع main، وتعرف اسم فرعك بالأمر git branch.

ربط المستودع البعيد git remote add

الأمر الذي ربطنا به المستودعين هو:

git remote add origin git@dvb-gitea:dev1/invoice-tool.git
git remote -v
origin	git@dvb-gitea:dev1/invoice-tool.git (fetch)
origin	git@dvb-gitea:dev1/invoice-tool.git (push)

والاسم origin مجرد اختصار محلي للرابط، تستطيع أن تسميه بأي اسم، ولكن الجميع يستخدم origin للمستودع الرئيسي، وتستطيع أن تضيف أكثر من مستودع بعيد بأسماء مختلفة كما في توثيق git remote. ولاحظ أن الرابط هنا بصيغة SSH وليس HTTP، فهو يبدأ بالمستخدم git ثم اسم السيرفر ثم نقطتين ثم المسار، وهذا يعني أن Git سوف يتصل بالسيرفر عبر SSH، وهنا تبدأ المرحلة التي يتعطل عندها أغلب المبتدئين.

الاتصال عبر SSH Keys

عندما تدفع عبر SSH يجب أن يحدث أمران: أن يتأكد جهازك أنه يتصل بالسيرفر الصحيح وليس بجهاز ينتحل اسمه، وأن يتأكد السيرفر أنك أنت صاحب الحساب. والأول يتم ببصمة السيرفر Host Key Fingerprint، والثاني بزوج مفاتيح Key Pair تنشئه على جهازك. والصورة التالية تبين الطريقتين اللتين سوف نشرحهما، SSH في هذا القسم وHTTPS في القسم الذي بعده:

صفان: الأول مفتاح SSH Key، فيه جهازك وقفل أخضر مع المفتاح الخاص يبقى عندك ~/.ssh/id_ed25519، وسهم أزرق إلى السيرفر مع توقيع بمفتاحك والسيرفر يتحقق بالمفتاح العام والرابط git@dvb-gitea:dev1/invoice-tool.git وأنت تتحقق من بصمة السيرفر Host Key Fingerprint، والمفتاح العام id_ed25519.pub في إعدادات حسابك. والثاني رمز وصول Access Token عبر HTTPS، فيه رمز بصلاحية محددة Scope write:repository، وسهم إلى السيرفر يرسل مع كل طلب بدلاً من الباسورد مع رابط https، وتلغيه وحده إذا تسرب ويبقى باسورد حسابك سليماً، وقائمة الرموز في Applications
المفتاح الخاص لا يغادر جهازك في SSH، والرمز في HTTPS يحل محل الباسورد

الخطأ الثاني: Host key verification failed

بعد أن أنشأنا ال Commit حاولنا الدفع، فظهر خطأ جديد:

Host key verification failed.
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

وفي الطرفية العادية يسألك SSH في أول اتصال بسيرفر جديد سؤالاً مثل «The authenticity of host … can't be established … Are you sure you want to continue connecting (yes/no)?»، ومعه بصمة مفتاح السيرفر، أما في مختبرنا فالأمر يعمل دون طرفية تفاعلية فلا يستطيع أن يسأل، فيرفض. وأغلب الناس يكتبون yes دون أن ينظروا، وهذا يلغي الحماية كلها، والسبب أن هذه البصمة هي الشيء الوحيد الذي يثبت أنك تتحدث مع سيرفرك وليس مع جهاز في منتصف الطريق. والطريقة الصحيحة أن تقارن البصمة التي يعرضها الاتصال ببصمة يعطيك إياها مسؤول السيرفر من طريق آخر، وفي المختبر نستطيع أن نرى الاثنين:

ssh-keyscan -t ed25519 dvb-gitea >> ~/.ssh/known_hosts
ssh-keygen -lf ~/.ssh/known_hosts

docker exec dvb-gitea ssh-keygen -lf /data/ssh/ssh_host_ed25519_key.pub
256 SHA256:xKDszO/GgxxsWHU31oQEi2i3IZ22kTM1gaFT4h6DPDw dvb-gitea (ED25519)

256 SHA256:xKDszO/GgxxsWHU31oQEi2i3IZ22kTM1gaFT4h6DPDw root@cbd39cdce34d (ED25519)

السطر الأول هو ما رآه جهازك، والثاني هو ما على السيرفر نفسه، والبصمتان متطابقتان، فنحن نتصل بالسيرفر الصحيح، ويحفظ SSH البصمة في الملف ~/.ssh/known_hosts فلا يسألك مرة ثانية. ومع GitHub وGitLab.com تجد البصمات الرسمية منشورة في صفحات التوثيق الخاصة بكل منهما، فقارن بها. وإذا ظهر لك يوماً تحذير كبير يقول إن مفتاح السيرفر تغير «REMOTE HOST IDENTIFICATION HAS CHANGED» فلا تحذف السطر القديم مباشرة، وإنما اسأل مسؤول السيرفر هل أعاد تثبيته أو غير مفاتيحه، لأن هذا التحذير هو بالضبط ما يظهر لو كان أحد ينتحل السيرفر.

الخطأ الثالث: Permission denied (publickey)

بعد أن عرف جهازك السيرفر حاولنا الدفع مرة أخرى:

git@dvb-gitea: Permission denied (publickey).
fatal: Could not read from remote repository.

Please make sure you have the correct access rights
and the repository exists.

الآن الاتصال وصل إلى السيرفر، والسيرفر رفض أن يعرف من أنت، والسبب أنه لا يقبل عبر SSH إلا المفاتيح، ولا يوجد عندنا أي مفتاح. ولاحظ أن كل المستخدمين يتصلون بنفس اسم المستخدم git، فالسيرفر لا يعرف هويتك من اسم المستخدم، وإنما من المفتاح الذي تقدمه، فيبحث عنه في قائمة المفاتيح المسجلة لكل الحسابات، ويعرف بذلك أنك dev1. ولذلك أيضاً فرسالة «make sure … the repository exists» قد تظهر والمستودع موجود، لأن Git يطبع الجملة نفسها لأي فشل في الاتصال.

إنشاء مفتاح Ed25519 ssh-keygen

نولد زوج مفاتيح من النوع Ed25519، وهو النوع الذي تنصح به اليوم أغلب المنصات لأنه قصير وسريع وآمن، أما RSA فيعمل أيضاً ولكن بطول 3072 بت على الأقل، وخيارات الأداة كلها في صفحة ssh-keygen:

ssh-keygen -t ed25519 -C "[email protected]" -f ~/.ssh/id_ed25519
cat ~/.ssh/id_ed25519.pub
ls -l ~/.ssh

والمخرج سوف يكون كما يلي:

Generating public/private ed25519 key pair.
Your identification has been saved in /root/.ssh/id_ed25519
Your public key has been saved in /root/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:Dq3D5FmQn4agrcMj8bOMrEnZ6h/nk9uiBov4kGb8lG4 [email protected]

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIBXeCJ1Fu9SqF/WNWtSVwQQEFexOB/Wj+GgQ1wazMWUK [email protected]

-rw-------    1 root     root           411 Nov  3 10:03 id_ed25519
-rw-r--r--    1 root     root            98 Nov  3 10:03 id_ed25519.pub
-rw-r--r--    1 root     root           127 Nov  3 10:03 known_hosts

في المخرج أعلاه لاحظ التالي:

  • الأداة أنشأت ملفين: id_ed25519 وهو المفتاح الخاص Private Key، وصلاحياته -rw------- أي أنك وحدك تقرؤه، وهذا الملف لا يغادر جهازك أبداً ولا ترسله لأحد ولا تضعه في أي مستودع، وid_ed25519.pub وهو المفتاح العام Public Key الذي تعطيه للسيرفر، ولا مشكلة في أن يراه أي شخص.
  • عند التشغيل في طرفيتك سوف يسألك ssh-keygen عن عبارة مرور Passphrase تحمي المفتاح الخاص، فإذا سرق جهازك أو نسخ الملف لا يستطيع أحد استخدامه دونها، فاكتب واحدة، واستخدم ssh-agent حتى لا تكتبها مع كل دفع. وفي المختبر استخدمنا عبارة فارغة بالخيار -N "" لأن الأمر يعمل دون طرفية.
  • الخيار -C مجرد تعليق في آخر المفتاح العام يساعدك على معرفة أي مفتاح هذا عندما يكون عندك عدة أجهزة.
  • على Windows يعمل الأمر نفسه في PowerShell أو Git Bash، ويحفظ الملفات في C:\Users\<اسمك>\.ssh.

الآن انسخ محتوى الملف .pub كاملاً، ثم افتح في Gitea Settings ← SSH / GPG Keys ← Add Key، والصقه مع اسم يدل على الجهاز:

صفحة User Settings في Gitea على تبويب SSH / GPG Keys، مع رسالة خضراء The SSH key laptop has been added، وتحت Manage SSH Keys المفتاح laptop مع البصمة SHA256:Dq3D5FmQn4agrcMj8bOMrEnZ6h/nk9uiBov4kGb8lG4 وAdded on Nov 3, 2026 وزرا Remove وVerify
المفتاح مسجل، والبصمة نفسها التي طبعها ssh-keygen على جهازك

لاحظ أن البصمة في الصفحة هي نفسها التي طبعها ssh-keygen، وهذا يؤكد أنك لصقت المفتاح الصحيح، وأن الاسم laptop يجعلك تعرف أي مفتاح تحذف إذا ضاع ذلك الجهاز. ونختبر الاتصال قبل الدفع:

ssh -T git@dvb-gitea
Hi there, dev1! You've successfully authenticated with the SSH key named laptop.
Gitea does not provide shell access. If this is unexpected, please setup Gitea under another SSH user or use container to deploy.

Gitea عرفك بالاسم من المفتاح، وأخبرك أنه لا يعطي طرفية Shell، وهذا متوقع لأن SSH هنا لأوامر Git فقط.

أكثر من حساب أو سيرفر: الملف ~/.ssh/config

بعد فترة سوف يكون عندك أكثر من حساب، مثل حساب للعمل على Gitea الشركة وحساب شخصي على GitHub، ولكل منهما مفتاح مختلف، وقد يعمل سيرفر Gitea في الشركة على منفذ SSH غير 22 لأن المنفذ 22 محجوز لإدارة السيرفر نفسه. وبدلاً من أن تكتب هذه التفاصيل في كل رابط، تضعها مرة واحدة في الملف ~/.ssh/config:

Host git.example.com
    User git
    Port 2222
    IdentityFile ~/.ssh/id_ed25519_work
    IdentitiesOnly yes

Host github.com
    User git
    IdentityFile ~/.ssh/id_ed25519_personal
    IdentitiesOnly yes

في الإعداد أعلاه لاحظ التالي:

  • كل كتلة Host تنطبق على الاتصالات بذلك الاسم، فيبقى رابط المستودع قصيراً مثل [email protected]:team/app.git، ويأخذ SSH المنفذ والمفتاح من الملف.
  • الخيار IdentitiesOnly yes يجعل SSH يقدم المفتاح المحدد فقط، والسبب أن SSH يجرب افتراضياً كل المفاتيح التي عنده بالترتيب، وبعض السيرفرات تقطع الاتصال بعد عدد محدود من المحاولات الفاشلة، فتظهر لك رسالة Too many authentication failures مع أن المفتاح الصحيح موجود.
  • إذا وضعت عبارة مرور على المفتاح، وهذا ما ننصح به، فأضفه إلى ssh-agent مرة في بداية الجلسة بالأمر ssh-add ~/.ssh/id_ed25519_work، فيحفظه الوكيل في الذاكرة ولا يسألك عن العبارة مع كل دفع، وعلى macOS وWindows يستطيع الوكيل أن يحفظها في مخزن النظام بين مرات التشغيل.

أول دفع First Push

الآن كل شيء جاهز للدفع:

git push -u origin main
git branch -vv
git status

والمخرج سوف يكون كما يلي:

To dvb-gitea:dev1/invoice-tool.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

* main 13ec719 [origin/main] Add invoice calculator with VAT

On branch main
Your branch is up to date with 'origin/main'.

nothing to commit, working tree clean

في المخرج أعلاه لاحظ التالي:

  • [new branch] main -> main يعني أن الفرع المحلي main أصبح فرعاً جديداً اسمه main على السيرفر.
  • الخيار -u اختصار --set-upstream، وهو يربط فرعك بالفرع البعيد كما تبين السطر [origin/main] في مخرج git branch -vv، ولذلك يكفي بعد ذلك أن تكتب git push وgit pull دون أسماء، ويعرف git status هل أنت متقدم على السيرفر أو متأخر عنه.

وعند فتح المستودع في المتصفح سوف تجد الملفات الأربعة وال Commit، وتحتها ملف README معروضاً كصفحة:

صفحة المستودع dev1/invoice-tool في Gitea بعد الدفع: 1 Commit و1 Branch و0 Tags، وآخر Commit من dev1 بالهاش 13ec7195fb Add invoice calculator with VAT، والملفات .env.example و.gitignore وinvoice.py وREADME.md، وتحتها README.md معروضاً بعنوان invoice-tool والنص Small invoice calculator with 15% VAT والأمر python invoice.py، وعلى الجانب الوصف Small invoice calculator واللغة Python 100%
المستودع بعد أول دفع، ولا أثر للملف .env ولا لمجلد __pycache__

لاحظ أن المنصة تعرض README.md تلقائياً في الصفحة الرئيسية، ولذلك فهو أول ما يقرؤه من يفتح مشروعك، فاكتب فيه ماذا يفعل المشروع وكيف يشغل وما المتغيرات التي يحتاجها، ولاحظ أيضاً أن .env و__pycache__ غير موجودين على السيرفر، فقد فعل .gitignore عمله.

البديل: HTTPS مع رمز وصول Access Token

قد تكون في شبكة تمنع المنفذ 22، أو لا تريد إدارة مفاتيح SSH على جهاز مؤقت، وهنا تستخدم رابط HTTPS بدلاً من SSH، والفرق بين البروتوكولات التي يستخدمها Git مشروح في فصل البروتوكولات في كتاب Pro Git. ولكن عبر HTTPS يحتاج السيرفر إلى اسم مستخدم وكلمة سر مع كل عملية دفع، ولا ننصح بأن تكون هذه الكلمة باسورد حسابك، والسبب أن الباسورد يفتح كل شيء في حسابك، وإذا حفظته في ملف على جهاز ثم تسرب فقد خسرت الحساب كله. وقد أوقفت GitHub قبول باسورد الحساب في عمليات Git منذ 13 أغسطس 2021 كما أعلنت في مدونتها، وأصبحت تطلب رمز وصول أو مفتاح SSH.

ورمز الوصول Access Token سلسلة طويلة تنشئها من حسابك، ولها صلاحيات محددة Scopes، وتستطيع أن تلغيها وحدها في أي وقت دون أن تغير باسورد الحساب. وفي Gitea تنشئه من Settings ← Applications ← Generate New Token، أو من الواجهة البرمجية كما في توثيق الواجهة البرمجية، وفي المختبر أنشأناه لجهاز الزميل بصلاحية الكتابة على المستودعات فقط:

curl -s -u 'dev1:Lab-Pass-2026!' -H 'Content-Type: application/json' \
  -X POST http://localhost:3471/api/v1/users/dev1/tokens \
  -d '{"name":"laptop2-git","scopes":["write:repository"]}'

والمخرج بعد إخفاء قيمة الرمز سوف يكون كما يلي:

{"id":1,"name":"laptop2-git","sha1":"<hidden>","token_last_eight":"b829cd72","scopes":["write:repository"],...}

يعرض Gitea قيمة الرمز مرة واحدة فقط عند إنشائه، فانسخها في وقتها، وبعد ذلك لا تظهر إلا آخر ثمانية أحرف منه في الحقل token_last_eight حتى تميزه في القائمة. والصلاحية write:repository تكفي للاستنساخ والدفع، ولا تسمح بتغيير إعدادات الحساب ولا بإدارة المفاتيح، فإذا تسرب الرمز فأقصى ما يفعله من يحمله هو الكتابة في المستودعات، وتلغيه وينتهي الأمر.

جهاز ثان: clone ثم pull

الآن يأتي جهاز الزميل dvb-laptop2، فيستنسخ المستودع عبر HTTP، ولأن المستودع عام في المختبر فالاستنساخ لا يحتاج إلى أي هوية، ثم يضيف سطراً إلى README يبين المخرج المتوقع من السكربت، ويحاول أن يدفع:

git config --global user.name "Dev Two"
git config --global user.email [email protected]
git clone http://dvb-gitea:3000/dev1/invoice-tool.git
cd invoice-tool
echo "    python invoice.py  # prints 345.0" >> README.md
git commit -qam "Document expected output"
GIT_TERMINAL_PROMPT=0 git push

والمخرج سوف يكون كما يلي:

Cloning into 'invoice-tool'...
fatal: could not read Username for 'http://dvb-gitea:3000': terminal prompts disabled

القراءة مسموحة للجميع في مستودع عام، أما الكتابة فتحتاج إلى هوية، وGit حاول أن يسأل عن اسم المستخدم، ولأننا منعنا السؤال بالمتغير GIT_TERMINAL_PROMPT=0 فشل مباشرة. وفي طرفيتك العادية سوف يسألك عن اسم المستخدم ثم كلمة السر، فتكتب اسم حسابك والرمز مكان كلمة السر. ولكي لا تكتبه مع كل دفع يحفظه Git عبر مساعد بيانات الدخول Credential Helper، وفي المختبر استخدمنا أبسطها:

git config --global credential.helper store
printf "http://dev1:%s@dvb-gitea:3000\n" "$TOKEN" > ~/.git-credentials
chmod 600 ~/.git-credentials
git push
To http://dvb-gitea:3000/dev1/invoice-tool.git
   13ec719..8084a61  main -> main

والمساعد store يحفظ الرمز في الملف ~/.git-credentials كنص واضح غير مشفر، كما يحذر توثيق git credential-store، ولذلك فهو مقبول في مختبر أو على سيرفر CI معزول، أما على جهازك اليومي فاستخدم المساعد الذي يحفظ في مخزن النظام الآمن: Git Credential Manager الذي يأتي مع Git for Windows، وosxkeychain على macOS، وlibsecret على Linux.

نرجع الآن إلى جهازك، فهو لا يعرف بعد أن الزميل دفع شيئاً. والأمر git fetch ينزل الجديد دون أن يلمس ملفاتك، ثم git pull يدمجه في فرعك:

git fetch
git status -sb
git pull
python3 invoice.py
tail -2 README.md
From dvb-gitea:dev1/invoice-tool
   13ec719..8084a61  main       -> origin/main
## main...origin/main [behind 1]

Updating 13ec719..8084a61
Fast-forward
 README.md | 1 +
 1 file changed, 1 insertion(+)

287.5
    python invoice.py
    python invoice.py  # prints 345.0

وهنا ظهرت مشكلة حقيقية لم نخطط لها، فالسطر الذي أضفناه من جهاز الزميل يقول إن السكربت يطبع 345.0، ولكن عندما شغلناه طبع 287.5، والحساب الصحيح فعلاً هو 200 زائد 50 يساوي 250، مضروبة في 1.15 تساوي 287.5. والرقم الخطأ كتبناه في README دون أن نشغل السكربت، ومر إلى السيرفر لأن لا أحد راجعه ولا شيء تحقق منه، وهذا بالضبط ما تمسكه مراجعة الكود Code Review في طلب دمج، أو اختبار آلي في خط CI يشغل السكربت ويقارن الناتج. وأصلحناه بCommit جديد من جهازك:

sed -i "s/# prints 345.0/# prints 287.5/" README.md
git diff
git commit -qam "Fix expected output in README"
git push
git log --oneline --graph
diff --git a/README.md b/README.md
index dd20ea9..75491e7 100644
--- a/README.md
+++ b/README.md
@@ -3,4 +3,4 @@
 Small invoice calculator with 15% VAT.

     python invoice.py
-    python invoice.py  # prints 345.0
+    python invoice.py  # prints 287.5
To dvb-gitea:dev1/invoice-tool.git
   8084a61..4530684  main -> main
* 4530684 Fix expected output in README
* 8084a61 Document expected output
* 13ec719 Add invoice calculator with VAT

ماذا يوجد داخل المجلد .git؟ Inside .git

بعد ثلاثة Commits على جهازك يستحق الأمر أن تنظر مرة واحدة داخل المجلد المخفي الذي أنشأه git init، حتى تعرف أن ما يسمى «الفرع» و«ال Commit» ملفات صغيرة عادية:

ls -1 .git
cat .git/HEAD
cat .git/refs/heads/main
git cat-file -p HEAD
COMMIT_EDITMSG
FETCH_HEAD
HEAD
ORIG_HEAD
config
description
hooks
index
info
logs
objects
refs

ref: refs/heads/main
453068497013553330824eaa7f07e9886cee22b7

tree 3d4966d0eaf14ea572ffea3ccf0cdc1c4b46e7c0
parent 8084a618ecf821147c39744339785fea5d72587d
author Dev One <[email protected]> 1793700398 +0000
committer Dev One <[email protected]> 1793700398 +0000

Fix expected output in README

في المخرج أعلاه لاحظ التالي:

  • الملف HEAD سطر واحد يقول إنك على الفرع main، والفرع نفسه ملف فيه هاش آخر Commit، وهذا هو المعنى الحرفي لقولنا إن الفرع مؤشر، ولذلك لم يكن الفرع موجوداً قبل أول Commit في خطأ src refspec.
  • ال Commit نص قصير فيه هاش الشجرة Tree التي تمثل كل الملفات، وهاش الأب Parent، والكاتب ووقته بثواني Unix، ثم الرسالة، فإذا تغير أي حرف في أي ملف تغير هاش الشجرة ثم هاش ال Commit، ولهذا لا يمكن تعديل التاريخ دون أن يلاحظ من يملك نسخة.
  • الملف config هو إعداد هذا المستودع وحده، وفيه رابط origin وربط الفرع، والمجلد hooks فيه أمثلة لخطافات Hooks تعمل قبل ال Commit أو الدفع، وهي المكان الذي يوضع فيه فحص الأسرار على جهازك.

لاحظ في مخرج git status -sb العبارة [behind 1]، أي أن السيرفر متقدم عليك بCommit واحد، ولاحظ أن pull كان من النوع Fast-forward لأنك لم تغير شيئاً منذ آخر دفع، فتحرك فرعك إلى الأمام فقط. أما إذا عدل الشخصان في الوقت نفسه فسوف يرفض السيرفر دفع الثاني حتى يجلب ويدمج، وقد شرحنا هذه الحالة بالتفصيل في نجرب الخطأ عمداً: عندما يرفض السيرفر الدفع.

ماذا يحدث إذا دفعت سراً؟ What If

الآن نجرب الخطأ الذي يقع فيه كثيرون، ونفهم لماذا لا يكفي إصلاحه بالطريقة البديهية. أضاف الزميل ملف إعداد للدفع الإلكتروني فيه مفتاح API، ونسي أن يضيفه إلى .gitignore، فدفعه. ثم انتبه، فأخرجه من التتبع وأضافه إلى .gitignore ودفع مرة ثانية، وظن أن المشكلة انتهت:

printf "[payments]\napi_key=sk_test_51LabOnlyNotReal\n" > settings.ini
git add . && git commit -qm "Add payment settings" && git push -q

git rm --cached -q settings.ini
echo settings.ini >> .gitignore
git add .gitignore && git commit -qm "Stop tracking settings.ini" && git push -q
git log --oneline -3
ls settings.ini
72fa72e Stop tracking settings.ini
6389fc6 Add payment settings
4530684 Fix expected output in README
settings.ini

الأمر git rm --cached أخرج الملف من المستودع وأبقاه على القرص، فالتطبيق ما زال يقرؤه، والملف لم يعد يظهر في صفحة المستودع على Gitea. ولكن ماذا عن التاريخ؟ لنبحث عن الملف في السجل، ثم نطلبه من السيرفر كما كان في ال Commit الذي أضافه:

git log --oneline -- settings.ini
curl -s http://dvb-gitea:3000/dev1/invoice-tool/raw/commit/6389fc6/settings.ini
72fa72e Stop tracking settings.ini
6389fc6 Add payment settings

[payments]
api_key=sk_test_51LabOnlyNotReal

المفتاح ما زال على السيرفر في ال Commit القديم، ويقرؤه أي شخص يعرف رابط ذلك ال Commit، وكل من استنسخ المستودع قبل أو بعد الإصلاح عنده نسخة منه على جهازه. والسبب أن Git يحفظ كل Commit كلقطة كاملة لا تتغير، وال Commit الجديد لا يمحو ما قبله وإنما يضيف فوقه، والصورة التالية تبين ذلك:

خط زمني لل Commits من اليمين إلى اليسار: 13ec719 أول Commit، ثم 4530684 تصحيح README، ثم 6389fc6 باللون الأحمر إضافة settings.ini ومنه خط متقطع إلى صندوق فيه [payments] api_key=sk_test_51Lab...، ثم 72fa72e بالأخضر git rm --cached الملف لم يعد متتبعاً، ثم الفرع main، وفوقها من يملك نسخة من المستودع أو يفتح رابط ال Commit القديم على السيرفر يقرأ المفتاح، وفي الأسفل الخطوة الأولى دائماً ألغ المفتاح من الخدمة وأصدر بديلاً ثم فكر في تنظيف التاريخ
نتيجة التجربة: الملف خرج من الفرع، وبقي في التاريخ

ولذلك فالخطوة الأولى عند تسريب أي سر هي أن تلغيه من الخدمة التي أصدرته وتصدر بديلاً، لأنك لا تعرف من رآه، ثم بعد ذلك تفكر في تنظيف التاريخ بأدوات تعيد كتابته، وهذا يحتاج إلى تنسيق مع كل من يملك نسخة. والأفضل من كل ذلك ألا يصل السر إلى المستودع أصلاً، بأن يفحص خط CI أو خطاف Hook على جهازك كل Commit بحثاً عن الأسرار، وقد شرحنا ذلك عملياً في اكتشاف الأسرار المسربة مع Gitleaks وTruffleHog.

📌
في أكتوبر 2022 أعلنت Toyota في بيان اعتذار رسمي أن الشركة التي طورت موقع مستخدمي خدمة T-Connect رفعت جزءاً من كود الموقع إلى حساب على GitHub بإعداد عام في ديسمبر 2017، مخالفة لقواعد التعامل مع الكود، وأن الكود كان فيه مفتاح وصول إلى سيرفر البيانات يكفي للوصول إلى 296,019 عنواناً بريدياً ورقماً لإدارة العملاء. وبقي الكود متاحاً قرابة خمس سنوات حتى اكتشفته الشركة في 15 سبتمبر 2022، فجعلته خاصاً في اليوم نفسه، وغيرت مفتاح الوصول في 17 سبتمبر. والدرس من الجهتين: جعل المستودع خاصاً لا يلغي ما رآه الناس عندما كان عاماً، والإصلاح الحقيقي كان تغيير المفتاح نفسه.

ماذا لو دفعت إلى مستودع غير موجود؟ Push to Create

قد تسأل: لماذا ننشئ المستودع من الواجهة أولاً؟ ألا يستطيع Git أن ينشئه عند أول دفع؟ لنجرب ذلك بمجلد ملاحظات جديد لا يوجد له مستودع على السيرفر:

mkdir -p /home/notes && cd /home/notes && git init -q
echo "# notes" > README.md && git add . && git commit -qm "First note"
git remote add origin git@dvb-gitea:dev1/notes.git
git push -u origin main
Error:
error: Push to create is not enabled for users.
error:
fatal: Could not read from remote repository.

Git نفسه لا ينشئ مستودعات على السيرفر، وإنما المنصة هي التي تقرر، وGitea يملك هذه الميزة باسم الدفع للإنشاء Push to Create، وهي مطفأة افتراضياً كما في توثيق Push to Create، والسبب أن خطأً إملائياً واحداً في اسم المستودع سوف ينشئ مستودعاً جديداً بدلاً من أن يعطيك خطأ. وإذا شغلناها بالمتغير GITEA__repository__ENABLE_PUSH_CREATE_USER=true ثم أعدنا تشغيل Gitea ودفعنا مرة ثانية:

To dvb-gitea:dev1/notes.git
 * [new branch]      main -> main
branch 'main' set up to track 'origin/main'.

وعندما سألنا الواجهة البرمجية عن المستودع الجديد وجدنا "private":true، أي أن Gitea ينشئ المستودع بالدفع خاصاً بشكل افتراضي، وهذا اختيار جيد، والإعداد الذي يتحكم به موجود مع بقية الإعدادات في دليل إعدادات Gitea. ونصيحتنا أن تتركها مطفأة على سيرفر الفريق، وأن ينشأ كل مستودع من الواجهة بقرار واضح عن اسمه وخصوصيته وصاحبه.

التنظيف Cleanup

docker rm -f dvb-gitea dvb-laptop dvb-laptop2
docker volume rm dvb-gitea-data
docker network rm dvb-net

الروتين اليومي Daily Workflow

بعد الإعداد الأول لن تحتاج إلى معظم ما سبق إلا عند جهاز جديد أو مشروع جديد، والعمل اليومي يصبح أربعة أوامر تقريباً:

  1. git pull في بداية اليوم، حتى تبدأ من آخر نسخة على السيرفر وتقل التعارضات.
  2. تعدل، ثم git status وgit diff لترى ما تغير فعلاً.
  3. git add للملفات التي تقصدها، ثم git commit برسالة واضحة لكل تغيير منطقي.
  4. git push عندما يكتمل جزء يستحق أن يراه الآخرون، ولا تؤجل الدفع أياماً لأن جهازك ليس نسخة احتياطية.

وفي فريق لا يدفع أحد مباشرة إلى main عادة، وإنما يعمل على فرع ويفتح طلب دمج يراجعه زميل، وهذا موضوع المقال التالي في المرحلة عن طلبات الدمج ومراجعة الكود، أما الدمج وإعادة التأسيس والتراجع فهي في Git في العمل اليومي: Merge وRebase وCherry-pick.

أخطاء شائعة Common Mistakes

  • إنشاء README على المنصة ثم دفع مستودع محلي: تاريخان لا علاقة بينهما، ورفض للدفع، فإما أن تنشئ المستودع فارغاً وتدفع، أو تنشئه بملفاته ثم تستنسخه وتنقل الكود إليه.
  • إضافة .gitignore بعد أول Commit: الملفات التي دخلت تبقى متتبعة، فأخرجها بالأمر git rm --cached، وإذا كان فيها سر فاعتبره مكشوفاً.
  • كتابة yes لسؤال بصمة السيرفر دون مقارنة: يلغي الحماية الوحيدة ضد من ينتحل السيرفر، فقارن البصمة بمصدر موثوق مرة واحدة.
  • نسخ المفتاح الخاص بدلاً من العام: المفتاح الذي تلصقه في المنصة يبدأ بـ ssh-ed25519 ويأتي من الملف الذي ينتهي بـ .pub، فإذا لصقت محتوى يبدأ بـ -----BEGIN OPENSSH PRIVATE KEY----- فقد كشفت مفتاحك الخاص، فاحذفه وأنشئ زوجاً جديداً.
  • استخدام باسورد الحساب عبر HTTPS: استخدم رمز وصول بصلاحية محدودة لكل جهاز، فإذا ضاع الجهاز ألغيت رمزه وحده.
  • بريد مختلف في user.email: ال Commits تظهر دون حسابك، فاضبط البريد المسجل في المنصة.
  • الدفع بالقوة --force لتجاوز رفض السيرفر: يمسح عمل زملائك من الفرع، فنفذ git pull ثم ادفع.

قائمة تحقق Checklist

الخطوةكيف تتأكد
الهوية مضبوطةgit config --global --list يعرض الاسم والبريد المسجل في المنصة وinit.defaultbranch=main
المستودع على المنصة فارغ وخاصصفحة Quick Guide تظهر، وعلامة القفل بجانب الاسم
.gitignore قبل أول git addgit status --short لا يعرض .env ولا ملفات البناء
بصمة السيرفر صحيحةالبصمة في known_hosts تطابق بصمة يعطيك إياها مسؤول السيرفر
مفتاح SSH بعبارة مرورssh -T git@السيرفر يرحب بك باسمك واسم المفتاح
أو رمز وصول محدودالرمز بصلاحية write:repository فقط، ومحفوظ في مخزن النظام الآمن
الفرع مربوط بالسيرفرgit branch -vv يعرض [origin/main]
README يشرح المشروعالصفحة الرئيسية للمستودع تعرض ماذا يفعل وكيف يشغل

ماذا تقرأ بعد ذلك؟ Next Steps

دليلإدارة النسخ وGit للمبتدئين: لماذا نحتاجها وكيف تعمللماذا تضيع الملفات بأسماء final_v2 ويمسح الزملاء عمل بعضهم، وكيف يحل Git ذلك على مشروع حقيقي من أول commit.دليلGit في العمل اليومي: الدمج والتراجع دون أن تخسر عملكمتى تستخدم Merge ومتى تستخدم Rebase، وكيف تنقل إصلاحاً إلى فرع الإصدار أو تسترجع عملاً ظننت أنه ضاع.دليلGitea: خادم Git خاص لفريقك على سيرفرككيف تثبت Gitea على سيرفرك حتى يبقى كود فريقك عندك بتجربة تشبه GitHub، مع النسخ الاحتياطي والتحديث.دليلSecrets Scanning: كيف تكتشف الأسرار المسربة في الكودكيف يخرج المفتاح من جهازك إلى تاريخ Git وخط CI، وكيف تكتشفه قبل غيرك، وماذا تفعل في الساعة الأولى بعد تسربه.

إذا أردت أن تفهم ما يحدث داخل Git عندما تنفذ هذه الأوامر فارجع إلى إدارة النسخ وGit للمبتدئين، وإذا أردت سيرفر Gitea حقيقياً لفريقك بنطاق وشهادة ونسخ احتياطي فاتبع تثبيت Gitea مع Docker Compose، ولكي تفهم لماذا نهتم بكل هذا في الصورة الكبيرة فاقرأ ما هو DevOps؟.

الخلاصة Summary

  • المستودع على جهازك كامل بتاريخه، ولكنه يحتاج إلى نسخة مشتركة على منصة استضافة كود حتى لا يضيع ولكي يعمل معك غيرك.
  • اضبط اسمك وبريدك واسم الفرع الافتراضي مرة واحدة، وأنشئ المستودع على المنصة فارغاً وخاصاً إذا كان عندك كود موجود.
  • أنشئ .gitignore قبل أول git add، وراجع git status قبل كل Commit، وضع أسماء المتغيرات في .env.example دون قيمها.
  • الأخطاء الثلاثة الأولى لها معنى واضح: src refspec يعني لا يوجد Commit أو اسم الفرع مختلف، وHost key verification failed يعني أن جهازك لا يعرف السيرفر بعد، وPermission denied (publickey) يعني أن السيرفر لا يعرف مفتاحك.
  • استخدم مفتاح Ed25519 بعبارة مرور عبر SSH، أو رمز وصول بصلاحية محدودة عبر HTTPS، ولا تستخدم باسورد الحساب.
  • السر الذي دخل Commit يبقى في التاريخ حتى لو حذفته بعد ذلك، فألغه من الخدمة أولاً، وافحص الكود قبل أن يدخل المستودع.

سجل التحديثات Changelog

  • نوفمبر 2026: كتابة المقال واختبار كل الخطوات على Gitea 28.3.0 مع git 2.54.0 وOpenSSH 10.3p1 على Alpine 3.24.3.
نشرة عرب رووت | ArabRoot

معرفة تستحق مكاناً في بريدك.

مقالات مختارة وأدوات مفيدة وأفكار لمشروعك القادم، في رسالة واحدة كل أسبوع.

يمكنك إلغاء الاشتراك متى شئت. الخصوصية

تم استلام طلبك. افتح بريدك واضغط رابط التأكيد لإتمام الاشتراك.