Tình huống lỗiĐiều này có thể xảy ra với bất kỳ ai. Bạn vừa kết thúc một phiên lập trình dài, gõ git push origin main, và thay vì thanh tiến trình thành công, terminal lại hiển thị một thông báo lỗi khó chịu:
git@github.com: Permission denied (publickey).
fatal: Could not read from remote repository.
Lỗi này có nghĩa là máy Mac của bạn đã cố gắng kết nối với một máy chủ như GitHub qua SSH, nhưng quá trình bắt tay (handshake) không thành công. Máy chủ không nhận diện được public key hoặc máy của bạn hoàn toàn không cung cấp key nào. Đây là một trở ngại phổ biến, đặc biệt là sau khi cập nhật macOS hoặc khi thiết lập một chiếc MacBook Pro mới.
Tại sao lỗi này xảy ra trên macOSTrên macOS Sonoma hoặc Ventura, nguyên nhân thường nằm ở bốn lý do cụ thể sau:
- Thiếu Key: Bạn chưa tạo cặp SSH key.- Danh tính chưa được liên kết: Key của bạn tồn tại cục bộ nhưng chưa được tải lên hồ sơ GitHub hoặc GitLab.- Reset khi khởi động lại: SSH agent của macOS thường "quên" các key sau khi bạn khởi động lại máy tính.- Quyền hạn nghiêm ngặt: SSH rất khắt khe về bảo mật. Nếu thư mục
.sshcủa bạn có quyền truy cập quá rộng (cho phép người dùng khác truy cập), macOS sẽ bỏ qua hoàn toàn các key của bạn để đảm bảo an toàn.## Bước 1: Kiểm tra các SSH key hiện cóĐừng lãng phí thời gian tạo bản sao nếu không cần thiết. Trước tiên, hãy kiểm tra những gì đã có sẵn bằng cách chạy lệnh:
ls -al ~/.ssh
Kiểm tra danh sách để tìm id_ed25519.pub hoặc id_rsa.pub. Nếu bạn thấy các tệp này, bạn đã đi được nửa chặng đường—hãy chuyển sang Bước 3. Nếu thư mục bị thiếu hoặc trống, đã đến lúc tạo một cái mới.
Bước 2: Tạo SSH key mớiCác tiêu chuẩn bảo mật hiện đại ưu tiên thuật toán Ed25519. Nó nhanh hơn và an toàn hơn so với tiêu chuẩn RSA cũ. Tạo key của bạn bằng lệnh này:
ssh-keygen -t ed25519 -C "your_email@example.com"
Nhấn Enter để chấp nhận vị trí tệp mặc định (/Users/yourname/.ssh/id_ed25519). Khi được hỏi mật khẩu (passphrase), hãy cung cấp một cái. Nó giúp thêm một lớp bảo mật quan trọng nếu laptop của bạn bị mất hoặc bị đánh cắp.
Bước 3: Cấu hình macOS SSH AgentĐây là điểm gây lỗi phổ biến nhất đối với người dùng Mac. Ngay cả khi key tồn tại, macOS sẽ không tự động sử dụng nó trừ khi được yêu cầu. Khởi động agent ở chế độ nền:
eval "$(ssh-agent -s)"
Bây giờ, chúng ta cần làm cho cấu hình này có hiệu lực vĩnh viễn để nó vẫn hoạt động sau khi khởi động lại. Tạo hoặc mở tệp cấu hình SSH của bạn:
nano ~/.ssh/config
Dán các dòng cụ thể sau vào trình chỉnh sửa:
Host github.com
AddKeysToAgent yes
UseKeychain yes
IdentityFile ~/.ssh/id_ed25519
Lưu ý: Nếu bạn đang sử dụng key RSA cũ hơn, hãy đổi dòng cuối cùng thành ~/.ssh/id_rsa.
Lưu và thoát bằng cách nhấn Ctrl+O, Enter, và Ctrl+X. Cuối cùng, liên kết key với macOS Keychain:
ssh-add --apple-use-keychain ~/.ssh/id_ed25519
Bước 4: Tải Public Key của bạn lênGitHub cần biết key này thuộc về bạn. Sao chép nội dung public key trực tiếp vào clipboard bằng phím tắt sau:
pbcopy < ~/.ssh/id_ed25519.pub
```- Truy cập vào **Settings** trên GitHub của bạn.- Nhấp vào **SSH and GPG keys** ở thanh bên trái.- Chọn **New SSH Key**.- Đặt cho nó một nhãn rõ ràng như "M3 MacBook Air - Office" và dán mã vào trường **Key**.## Bước 5: Thắt chặt quyền tệp tinNếu quyền của bạn bị sai, SSH sẽ âm thầm thất bại. Thư mục `.ssh` của bạn phải là một kho lưu trữ riêng tư. Đặt thư mục thành `700` (chỉ bạn có quyền đọc/ghi/thực thi) và key thành `600` (chỉ bạn có quyền đọc/ghi):
chmod 700 ~/.ssh chmod 600 ~/.ssh/id_ed25519
Nếu bạn không chắc chắn về các con số này, một [Công cụ tính quyền Unix](https://toolcraft.app/en/tools/developer/unix-permissions) có thể giúp bạn hình dung mặt nạ bit (bitmask). Ví dụ, `600` đảm bảo không có người dùng "Group" hoặc "World" nào có thể xem trộm dữ liệu riêng tư của bạn.
## Bước 6: Kiểm tra kết quảKiểm tra kết nối mà không cần thực sự đẩy mã nguồn:
ssh -T git@github.com
Thiết lập thành công sẽ trả về: *"Hi [your-username]! You've successfully authenticated, but GitHub does not provide shell access."*
### Xử lý sự cố nhanh- **Sai giao thức:** Kiểm tra lại URL remote của bạn. Sử dụng `git remote -v`. Nếu nó bắt đầu bằng `https://`, SSH key của bạn sẽ không được sử dụng. Hãy chuyển đổi nó bằng lệnh `git remote set-url origin git@github.com:user/repo.git`.- **Nhiều tài khoản:** Nếu bạn dùng lẫn lộn tài khoản công việc và cá nhân, tệp `~/.ssh/config` của bạn cần các mục `Host` riêng biệt cho mỗi tài khoản để tránh nhầm lẫn danh tính.