GitHub Deploy Key چیست؟ آموزش ساخت و استفاده امن

اگر برای استقرار پروژه روی سرور، اجرای CI/CD یا دریافت خودکار آخرین تغییرات به یک مخزن خصوصی GitHub نیاز دارید، باید روشی امن برای احراز هویت سرور داشته باشید. یکی از ساده‌ترین روش‌ها برای این کار، استفاده از GitHub Deploy Key است.

Deploy Key یک کلید SSH است که مستقیماً به یک Repository متصل می‌شود. برخلاف SSH Key معمولی که به حساب کاربری تعلق دارد، Deploy Key تنها به همان مخزنی دسترسی دارد که برای آن تعریف شده است. این ویژگی سطح دسترسی سرور را محدود می‌کند و امنیت فرایند استقرار را افزایش می‌دهد.

در این آموزش، ساخت Deploy Key، افزودن آن به GitHub، اتصال امن سرور و رفع خطاهای متداول را مرحله‌به‌مرحله بررسی می‌کنیم.

GitHub Deploy Key چیست؟

GitHub Deploy Key یک کلید SSH برای دسترسی خودکار یک سرور یا سرویس استقرار به یک مخزن مشخص است.

هر کلید SSH از دو بخش تشکیل می‌شود:

• Public Key: در تنظیمات Repository در GitHub ثبت می‌شود.

• Private Key: فقط روی سرور یا سرویس استقرار باقی می‌ماند.

هنگامی که سرور به GitHub متصل می‌شود، GitHub با استفاده از Public Key اعتبار Private Key موجود روی سرور را بررسی می‌کند. در این روش نیازی به واردکردن نام کاربری، رمز عبور یا Personal Access Token در هر بار استقرار نیست.

طبق مستندات رسمی GitHub درباره Deploy Key، این کلید به‌صورت پیش‌فرض فقط دسترسی خواندن دارد و تنها برای یک Repository قابل استفاده است.

Deploy Key چه تفاوتی با SSH Key معمولی دارد؟

SSH Key معمولی به حساب کاربری GitHub متصل می‌شود و می‌تواند به تمام مخزن‌هایی دسترسی داشته باشد که آن حساب اجازه دسترسی به آن‌ها را دارد.

Deploy Key به یک حساب شخصی متصل نیست. این کلید مستقیماً در تنظیمات یک Repository قرار می‌گیرد و فقط به همان مخزن دسترسی دارد.

تفاوت‌های اصلی عبارت‌اند از:

• Deploy Key تنها به یک Repository دسترسی دارد.

• SSH Key حساب کاربری ممکن است به چندین Repository دسترسی داشته باشد.

• Deploy Key برای سرورها و فرایندهای خودکار مناسب‌تر است.

• Deploy Key تاریخ انقضای خودکار ندارد و باید به‌صورت دوره‌ای بررسی یا تعویض شود.

• حذف کاربری که Deploy Key را ساخته است، باعث غیرفعال‌شدن آن کلید نمی‌شود.

اگر یک سرور فقط باید پروژه مشخصی را دریافت و اجرا کند، Deploy Key معمولاً انتخاب ساده و مناسبی است. برای مدیریت دسترسی به تعداد زیادی Repository، استفاده از GitHub App می‌تواند کنترل دقیق‌تری فراهم کند.

چه زمانی باید از Deploy Key استفاده کنیم؟

Deploy Key در سناریوهای زیر کاربرد دارد:

• دریافت پروژه خصوصی GitHub روی سرور لینوکس

• اجرای خودکار git pull هنگام استقرار

• اتصال ابزارهای CI/CD به یک Repository

• استقرار پروژه از طریق Docker یا اسکریپت‌های سرور

• اتصال یک سرویس میزبانی به مخزن خصوصی

• محدودکردن دسترسی سرور به یک پروژه مشخص

اگر سرور فقط باید کد را دریافت کند، دسترسی Read-only کافی است. فعال‌کردن دسترسی نوشتن تنها زمانی منطقی است که سرور واقعاً باید تغییراتی را به Repository ارسال کند.

آموزش ساخت GitHub Deploy Key

مرحله اول: ورود به سرور

ابتدا با SSH به سروری متصل شوید که قرار است پروژه روی آن اجرا شود:

ssh username@server-ip

به‌جای username نام کاربری سرور و به‌جای server-ip آدرس IP یا دامنه سرور را وارد کنید.

مرحله دوم: بررسی کلیدهای موجود

برای مشاهده کلیدهای SSH موجود، دستور زیر را اجرا کنید:

ls -la ~/.ssh

ممکن است فایل‌هایی مانند موارد زیر مشاهده کنید:

id_ed25519
id_ed25519.pub
id_rsa
id_rsa.pub

برای Deploy Key بهتر است یک کلید اختصاصی با نام مشخص ایجاد کنید. استفاده از کلید جداگانه باعث می‌شود مدیریت و تعویض دسترسی هر پروژه آسان‌تر باشد.

مرحله سوم: ساخت کلید SSH اختصاصی

برای ساخت کلید ED25519 دستور زیر را اجرا کنید:

ssh-keygen -t ed25519 -C "deploy@example.com" -f ~/.ssh/github_deploy_key

می‌توانید مقدار deploy@example.com را با یک عنوان قابل‌شناسایی مانند ایمیل فنی یا نام پروژه جایگزین کنید.

این دستور دو فایل ایجاد می‌کند:

~/.ssh/github_deploy_key
~/.ssh/github_deploy_key.pub

فایل بدون پسوند، Private Key است و نباید در اختیار دیگران قرار بگیرد. فایل دارای پسوند .pub همان Public Key است که باید در GitHub ثبت شود.

اگر سیستم شما از ED25519 پشتیبانی نمی‌کند، می‌توانید از RSA استفاده کنید:

ssh-keygen -t rsa -b 4096 -C "deploy@example.com" -f ~/.ssh/github_deploy_key

مشاهده و کپی Public Key

برای نمایش Public Key دستور زیر را اجرا کنید:

cat ~/.ssh/github_deploy_key.pub

خروجی معمولاً با ssh-ed25519 یا ssh-rsa شروع می‌شود. تمام خروجی را در یک خط کپی کنید.

نمونه:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAA... deploy@example.com

فقط Public Key را در GitHub وارد کنید. فایل Private Key را در ایمیل، پیام‌رسان، GitHub یا فایل‌های پروژه قرار ندهید.

افزودن Deploy Key به Repository در GitHub

برای افزودن کلید مراحل زیر را انجام دهید:

1. وارد Repository موردنظر در GitHub شوید.

2. وارد بخش Settings شوید.

3. از منوی سمت چپ گزینه Deploy keys را انتخاب کنید.

4. روی Add deploy key کلیک کنید.

5. در قسمت Title یک نام مشخص مانند Production Server وارد کنید.

6. Public Key را در قسمت Key قرار دهید.

7. در صورت نیاز، وضعیت Allow write access را تعیین کنید.

8. روی Add key کلیک کنید.

بهتر است عنوان کلید شامل نام محیط یا سرور باشد؛ برای مثال:

Production Server - Tehran

این نام‌گذاری کمک می‌کند بعداً بدانید هر کلید متعلق به کدام سرور است.

آیا Allow write access را فعال کنیم؟

Deploy Key به‌صورت پیش‌فرض Read-only است. با این سطح دسترسی، سرور می‌تواند Repository را Clone یا Pull کند، اما اجازه Push ندارد.

برای بیشتر فرایندهای استقرار، دسترسی خواندن کافی است. گزینه Allow write access را فقط زمانی فعال کنید که سرور باید تغییراتی مانند فایل تولیدشده، نسخه جدید یا Commit خودکار را به مخزن ارسال کند.

فعال‌کردن دسترسی نوشتن بدون نیاز واقعی، دامنه خسارت احتمالی در صورت نفوذ به سرور را افزایش می‌دهد.

تنظیم فایل SSH Config

برای اینکه Git دقیقاً از کلید ساخته‌شده استفاده کند، فایل تنظیمات SSH را باز کنید:

nano ~/.ssh/config

تنظیمات زیر را به آن اضافه کنید:

Host github-deploy
    HostName github.com
    User git
    IdentityFile ~/.ssh/github_deploy_key
    IdentitiesOnly yes

سپس سطح دسترسی فایل‌ها را محدود کنید:

chmod 700 ~/.ssh
chmod 600 ~/.ssh/github_deploy_key
chmod 644 ~/.ssh/github_deploy_key.pub
chmod 600 ~/.ssh/config

مقدار IdentitiesOnly yes باعث می‌شود SSH فقط از کلیدی استفاده کند که در این بخش مشخص کرده‌اید.

آزمایش اتصال SSH به GitHub

پس از ثبت Public Key، اتصال را آزمایش کنید:

ssh -T git@github-deploy

در اولین اتصال ممکن است درباره معتبر بودن میزبان سؤال شود. قبل از تأیید، اثر انگشت نمایش‌داده‌شده را با اثر انگشت‌های رسمی کلیدهای GitHub مقایسه کنید.

اگر اتصال درست باشد، GitHub پیامی درباره موفقیت احراز هویت نمایش می‌دهد. GitHub دسترسی Shell ارائه نمی‌کند؛ بنابراین بسته‌شدن دستور با کد خروجی غیرصفر همیشه به معنی ناموفق‌بودن احراز هویت نیست.

Clone کردن Repository با Deploy Key

پس از تنظیم Alias در فایل SSH Config، مخزن را با دستور زیر دریافت کنید:

git clone git@github-deploy:OWNER/REPOSITORY.git

مقادیر زیر را جایگزین کنید:

• OWNER: نام کاربری یا Organization

• REPOSITORY: نام Repository

نمونه:

git clone git@github-deploy:example/my-project.git

اگر پروژه قبلاً با HTTPS دریافت شده است، آدرس Remote را تغییر دهید:

git remote set-url origin git@github-deploy:OWNER/REPOSITORY.git

برای بررسی آدرس جدید اجرا کنید:

git remote -v

سپس اتصال را با دریافت اطلاعات Repository آزمایش کنید:

git fetch origin

استفاده از چند Repository روی یک سرور

یک Deploy Key را نمی‌توان هم‌زمان برای چند Repository استفاده کرد. برای هر Repository باید یک جفت کلید اختصاصی بسازید.

برای نمونه، دو کلید جداگانه ایجاد کنید:

ssh-keygen -t ed25519 -f ~/.ssh/project_one_deploy_key
ssh-keygen -t ed25519 -f ~/.ssh/project_two_deploy_key

سپس برای هر پروژه یک Alias در فایل ~/.ssh/config قرار دهید:

Host github-project-one
    HostName github.com
    User git
    IdentityFile ~/.ssh/project_one_deploy_key
    IdentitiesOnly yes

Host github-project-two
    HostName github.com
    User git
    IdentityFile ~/.ssh/project_two_deploy_key
    IdentitiesOnly yes

اکنون هر Repository با Alias مخصوص خود دریافت می‌شود:

git clone git@github-project-one:OWNER/PROJECT_ONE.git
git clone git@github-project-two:OWNER/PROJECT_TWO.git

این روش از تداخل کلیدها جلوگیری می‌کند و امکان حذف دسترسی یک پروژه بدون تأثیر روی پروژه دیگر را فراهم می‌سازد.

نکات امنیتی مهم برای Deploy Key

Private Key را منتشر نکنید

Private Key نباید وارد Repository، Docker Image، فایل عمومی، پیام‌رسان یا سیستم ثبت لاگ شود. فایل‌هایی مانند موارد زیر باید محرمانه باقی بمانند:

github_deploy_key
id_ed25519
id_rsa

اصل حداقل دسترسی را رعایت کنید

اگر سرور فقط به Clone و Pull نیاز دارد، Deploy Key را Read-only نگه دارید. مجوز نوشتن را بدون دلیل فعال نکنید.

برای هر Repository کلید جداگانه بسازید

کلید اختصاصی امکان مدیریت، بررسی و لغو دسترسی هر پروژه را ساده‌تر می‌کند.

کلیدهای قدیمی را بررسی کنید

Deploy Key تاریخ انقضای خودکار ندارد. به همین دلیل باید کلیدهای بدون استفاده را از مسیر زیر حذف کنید:

Repository → Settings → Deploy keys

دسترسی فایل Private Key را محدود کنید

در لینوکس سطح دسترسی Private Key باید محدود باشد:

chmod 600 ~/.ssh/github_deploy_key

از سرور محافظت کنید

هر شخص یا فرایندی که به Private Key دسترسی پیدا کند، می‌تواند مطابق سطح مجوز کلید به Repository دسترسی داشته باشد. امنیت Deploy Key مستقیماً به امنیت سرور وابسته است.

خطای Permission denied (publickey)

این خطا یعنی GitHub نتوانسته است کلید مناسب را برای احراز هویت پیدا یا تأیید کند:

Permission denied (publickey)

موارد زیر را بررسی کنید:

1. Public Key صحیح در Repository ثبت شده باشد.

2. مسیر IdentityFile در فایل SSH Config درست باشد.

3. سطح دسترسی Private Key برابر 600 باشد.

4. آدرس Remote از Alias تعریف‌شده استفاده کند.

5. فایل Private Key ناقص یا تغییر داده نشده باشد.

برای مشاهده جزئیات اتصال از حالت Verbose استفاده کنید:

ssh -vT git@github-deploy

در خروجی این دستور می‌توانید ببینید SSH کدام کلیدها را آزمایش می‌کند.

خطای Repository not found

اگر این خطا نمایش داده شود:

Repository not found

موارد زیر را بررسی کنید:

• نام Owner و Repository صحیح باشد.

• Deploy Key به Repository درست اضافه شده باشد.

• آدرس Remote اشتباه تایپی نداشته باشد.

• Repository حذف یا تغییر نام داده نشده باشد.

آدرس Remote را با دستور زیر بررسی کنید:

git remote -v

خطای Key is already in use

GitHub اجازه نمی‌دهد یک Deploy Key یکسان برای چند Repository استفاده شود. اگر با خطای زیر مواجه شدید:

Key is already in use

برای Repository جدید، یک کلید SSH جدید بسازید. کپی‌کردن همان Public Key و استفاده مجدد از آن راه‌حل مناسبی نیست.

حذف یا تعویض Deploy Key

برای حذف کلید قدیمی وارد مسیر زیر شوید:

Repository → Settings → Deploy keys

Deploy Key موردنظر را پیدا و حذف کنید. سپس فایل Private Key مرتبط را نیز از سروری که دیگر به آن نیاز ندارد پاک کنید.

برای تعویض کلید:

1. یک جفت کلید جدید روی سرور بسازید.

2. Public Key جدید را به Repository اضافه کنید.

3. فایل SSH Config را به‌روزرسانی کنید.

4. اتصال را آزمایش کنید.

5. Deploy Key قدیمی را از GitHub حذف کنید.

6. Private Key قدیمی را از سرور حذف کنید.

بهتر است ابتدا اتصال کلید جدید را آزمایش و سپس کلید قبلی را حذف کنید تا استقرار پروژه متوقف نشود.

Deploy Key بهتر است یا Personal Access Token؟

انتخاب روش احراز هویت به ساختار پروژه بستگی دارد:

• برای دسترسی SSH یک سرور به یک Repository، Deploy Key ساده و محدود است.

• برای دسترسی به چند Repository، GitHub App معمولاً مدیریت و کنترل دقیق‌تری ارائه می‌دهد.

• برای عملیات مبتنی بر HTTPS یا GitHub API می‌توان از توکن‌های محدودشده استفاده کرد.

• برای عملیات کاربری تعاملی، SSH Key حساب شخصی مناسب‌تر است.

GitHub برای دسترسی‌های پیچیده و چندمخزنی، استفاده از GitHub App با مجوزهای محدود و توکن‌های کوتاه‌مدت را پیشنهاد می‌کند.

جمع‌بندی

GitHub Deploy Key روشی ساده برای اتصال امن سرور یا سرویس استقرار به یک Repository مشخص است. در این روش، Public Key داخل تنظیمات Repository قرار می‌گیرد و Private Key فقط روی سرور باقی می‌ماند.

برای حفظ امنیت، یک کلید جداگانه برای هر Repository بسازید، دسترسی را تا حد امکان Read-only نگه دارید، Private Key را منتشر نکنید و کلیدهای قدیمی را به‌صورت دوره‌ای بررسی کنید.

با تنظیم صحیح Deploy Key می‌توانید عملیات Clone، Pull و استقرار خودکار پروژه را بدون ذخیره رمز حساب GitHub روی سرور انجام دهید.

سوالات متداول

آیا GitHub Deploy Key رایگان است؟

بله. قابلیت Deploy Key برای Repositoryهای GitHub قابل استفاده است و هزینه جداگانه‌ای ندارد.

آیا یک Deploy Key را می‌توان برای چند Repository استفاده کرد؟

خیر. هر Deploy Key فقط به یک Repository متصل می‌شود. برای هر Repository باید یک کلید اختصاصی ایجاد کنید.

آیا Deploy Key تاریخ انقضا دارد؟

خیر. Deploy Key به‌صورت خودکار منقضی نمی‌شود. مدیر Repository باید کلیدهای قدیمی و بدون استفاده را بررسی و حذف کند.

آیا فعال‌کردن Allow write access ضروری است؟

خیر. برای Clone و Pull کردن پروژه، دسترسی پیش‌فرض Read-only کافی است. این گزینه را فقط زمانی فعال کنید که سرور باید روی Repository عملیات Push انجام دهد.

تفاوت Deploy Key با Personal Access Token چیست؟

Deploy Key از SSH استفاده می‌کند و به یک Repository محدود است. Personal Access Token معمولاً برای HTTPS یا GitHub API استفاده می‌شود و سطح دسترسی آن با Scope یا Permission تعیین می‌شود.

اگر Private Key افشا شود چه کاری باید انجام دهیم؟

Deploy Key را فوراً از تنظیمات Repository حذف کنید، یک جفت کلید جدید بسازید و فایل Private Key قبلی را از تمام سرورها و سرویس‌ها پاک کنید.

آیا Deploy Key بعد از حذف سازنده آن غیرفعال می‌شود؟

خیر. Deploy Key به Repository متصل است، نه حساب کاربری سازنده. حذف یا قطع دسترسی کاربر سازنده لزوماً Deploy Key را غیرفعال نمی‌کند.

https://lnkd.in/p/dYn-mEku

مدیریت Deploy Key در مستندات GitHub

REST API مربوط به Deploy Key

بازبینی Deploy Keyهای حساب