SSH (Secure Shell) là phương pháp xác thực an toàn và tiện lợi để tương tác với GitLab. Khi cấu hình xong, bạn có thể đẩy/méo mã mà không cần nhập mật khẩu, đồng thời đảm bảo kết nối được mã hóa đầu cuối. Hướng dẫn này bao gồm đầy đủ quy trình từ tạo khóa, thiết lập commit có chữ ký, hỗ trợ nhiều tài khoản đến xử lý sự cố thường gặp. > **Áp dụng cho**: cả GitLab.com và các phiên bản tự quản lý (Self-Managed). Các lệnh đã được kiểm thử trên Windows (Git Bash / PowerShell), macOS và Linux.

1. Chuẩn bị ban đầu

Trước khi bắt đầu, hãy đảm bảo:

Mục	Yêu cầu	Lệnh kiểm tra
Git	Đã cài đặt (phiên bản ≥ 2.34)	git --version
OpenSSH	Client khả dụng	ssh -V
Terminal	Linux/macOS: dùng terminal mặc định; Windows: dùng Git Bash hoặc PowerShell, tránh CMD	—
Tài khoản GitLab	Có quyền đăng nhập và thêm SSH key	—

> Trong bài viết, ~/.ssh/ ám chỉ thư mục .ssh trong thư mục home của người dùng. Trên Windows, đường dẫn tương ứng là C:\Users\<username>\.ssh\.

2. Thiết lập nhanh (5 bước cơ bản)

Người dùng đã quen có thể làm theo các bước sau:

# 1. Tạo khóa Ed25519 (nhấn Enter để dùng đường dẫn mặc định, đặt passphrase)
ssh-keygen -t ed25519 -C "your_email@example.com"

# 2. Sao chép public key
cat ~/.ssh/id_ed25519.pub        # Copy thủ công
# hoặc
clip < ~/.ssh/id_ed25519.pub     # Windows (Git Bash)
pbcopy < ~/.ssh/id_ed25519.pub   # macOS

# 3. Đăng nhập GitLab → Avatar → Edit profile → SSH Keys → Add new key → dán nội dung

# 4. Kiểm tra kết nối
ssh -T git@gitlab.com            # Phản hồi: "Welcome to GitLab, @username!"

# 5. Clone repo
git clone git@gitlab.com:username/repo.git

Gặp lỗi? Xem phần Xử lý sự cố ở cuối bài.

3. Tạo cặp khóa SSH

Mỗi cặp khóa gồm: - Private key: lưu cục bộ, tuyệt đối không chia sẻ. - Public key: tải lên GitLab.

3.1 Chọn loại khóa

Loại	Khuyến nghị	Ghi chú
Ed25519	Ưu tiên	An toàn hơn, ngắn gọn, hiệu năng cao; được GitLab 14.8+ đề xuất
ECDSA (NIST)	Dùng được	Có tranh cãi về độ tin cậy của đường cong NIST
RSA (≥ 3072 bit)	Tương thích	Nên chọn 4096 bit nếu dùng RSA
DSA / RSA < 2048	Cấm dùng	Đã bị GitLab và OpenSSH loại bỏ

3.2 Lệnh tạo khóa

Kiểu Ed25519 (khuyến khích):

ssh-keygen -t ed25519 -C "your_email@example.com"

Kiểu RSA (cho hệ thống cũ):

ssh-keygen -t rsa -b 4096 -C "your_email@example.com"

Giải thích tham số:

Tham số	Mô tả
-t	Loại khóa (ed25519 hoặc rsa)
-b 4096	Chỉ áp dụng cho RSA, chỉ định độ dài khóa
-C	Chú thích nhận diện (không ảnh hưởng chức năng)

3.3 Hiểu các lời nhắc

1. Đường dẫn lưu file: nhấn Enter để dùng mặc định: - Ed25519 → ~/.ssh/id_ed25519 - RSA → ~/.ssh/id_rsa 2. Passphrase: nên đặt để tăng bảo mật. Kết hợp với SSH Agent sẽ tránh nhập lại nhiều lần. 3. Thông báo thành công:

Your identification has been saved in /home/user/.ssh/id_ed25519
Your public key has been saved in /home/user/.ssh/id_ed25519.pub
The key fingerprint is:
SHA256:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx your_email@example.com

> ⚠️ Lưu ý bảo mật: file có đuôi .pub là public key — có thể chia sẻ; file không đuôi là private key — tuyệt đối không tiết lộ.

4. Tải public key lên GitLab

4.1 Sao chép nội dung public key

Xem nội dung:

cat ~/.ssh/id_ed25519.pub

Sao chép nguyên văn, bao gồm phần đầu (`ssh-ed25519` hoặc `ssh-rsa`) và email cuối cùng. Lệnh sao chép nhanh theo hệ điều hành:

Hệ điều hành	Lệnh
macOS	pbcopy < ~/.ssh/id_ed25519.pub
Linux (X11)	xclip -sel clip < ~/.ssh/id_ed25519.pub
Linux (Wayland)	wl-copy < ~/.ssh/id_ed25519.pub
Windows (Git Bash)	clip < ~/.ssh/id_ed25519.pub
Windows (PowerShell)	Get-Content ~/.ssh/id_ed25519.pub | Set-Clipboard

4.2 Thêm vào GitLab

1. Đăng nhập → Nhấp avatar → Edit profile 2. Menu trái → SSH Keys → Add new key 3. Điền thông tin:

Trường	Mô tả
Key	Dán toàn bộ nội dung public key
Title	Tên mô tả, ví dụ: MacBook-Pro-2024
Usage type	Authentication & Signing (mặc định), hoặc riêng lẻ
Expiration date	Nên đặt để luân chuyển khóa định kỳ

4. Nhấn Add key.

5. Kiểm tra kết nối SSH

# Với GitLab.com
ssh -T git@gitlab.com

# Với GitLab tự quản (thay domain phù hợp)
ssh -T git@gitlab.yourcompany.com

- Lần đầu kết nối sẽ hỏi xác nhận dấu vân máy chủ. So sánh với danh sách chính thức trước khi gõ yes. - Thành công: Welcome to GitLab, @username! - Nếu treo: thêm cờ -v để debug: ssh -Tv git@gitlab.com.

6. Cấu hình SSH Agent

SSH Agent lưu private key đã giải mã trong phiên làm việc, tránh nhập passphrase lặp.

6.1 Linux / macOS

eval "$(ssh-agent -s)"
ssh-add ~/.ssh/id_ed25519
ssh-add -l  # Liệt kê khóa đã nạp

macOS (lưu vào Keychain):

ssh-add --apple-use-keychain ~/.ssh/id_ed25519

Thêm vào ~/.ssh/config:

Host *
  UseKeychain yes
  AddKeysToAgent yes
  IdentityFile ~/.ssh/id_ed25519

6.2 Windows

Bật dịch vụ ssh-agent (chạy PowerShell với quyền admin):

Set-Service -Name ssh-agent -StartupType Automatic
Start-Service ssh-agent
ssh-add $env:USERPROFILE\.ssh\id_ed25519

> (Tùy chọn) Ép Git dùng OpenSSH hệ thống: >

git config --global core.sshCommand "C:/Windows/System32/OpenSSH/ssh.exe"

7. Sử dụng hàng ngày

7.1 Clone dự án

git clone git@gitlab.com:username/repository.git

URL lấy từ nút Clone → Clone with SSH trên giao diện GitLab.

7.2 Chuyển từ HTTPS sang SSH

git remote set-url origin git@gitlab.com:username/repository.git
git remote -v  # Xác nhận thay đổi

7.3 Quản lý nhiều tài khoản / nhiều instance

Dùng file ~/.ssh/config để phân biệt:

# Công ty (self-hosted)
Host gitlab-work
  HostName gitlab.company.com
  User git
  IdentityFile ~/.ssh/id_ed25519_work
  IdentitiesOnly yes

# Cá nhân (GitLab.com)
Host gitlab-personal
  HostName gitlab.com
  User git
  IdentityFile ~/.ssh/id_ed25519_personal
  IdentitiesOnly yes

Khi clone:

git clone git@gitlab-work:group/project.git
git clone git@gitlab-personal:user/project.git

> IdentitiesOnly yes giúp SSH chỉ dùng đúng khóa được chỉ định, tránh thử tất cả khóa trong agent.

8. Nâng cao: Ký commit bằng SSH

Từ GitLab 15.7+, bạn có thể ký commit/tag bằng SSH key để hiển thị huy hiệu Verified.

git config --global gpg.format ssh
git config --global user.signingkey ~/.ssh/id_ed25519.pub
git config --global commit.gpgsign true
git config --global tag.gpgsign true

> Yêu cầu: khi thêm public key vào GitLab, chọn Usage type bao gồm Signing.

9. Xử lý sự cố

9.1 Permission denied (publickey)

Kiểm tra theo thứ tự: 1. URL remote phải bắt đầu bằng git@, không phải https:// → git remote -v 2. Public key đã dán đúng, không bị ngắt dòng 3. Private key đã được nạp vào agent → ssh-add -l 4. Dùng ssh -Tv git@gitlab.com để xem SSH đang thử khóa nào 5. Kiểm tra quyền truy cập file (xem 9.5)

9.2 Không kết nối được do cổng 22 bị chặn

Nhiều mạng doanh nghiệp chặn cổng 22. GitLab.com hỗ trợ cổng 443 qua tên miền thay thế. Thêm vào ~/.ssh/config:

Host gitlab.com
  Hostname altssh.gitlab.com
  Port 443
  User git
  PreferredAuthentications publickey
  IdentityFile ~/.ssh/id_ed25519

> Với GitLab tự quản, cần cấu hình tường lửa hoặc dùng HTTPS + Personal Access Token.

9.3 Vẫn yêu cầu nhập mật khẩu

- Nếu remote là HTTPS → chuyển sang SSH (xem 7.2) - Trên Windows: kiểm tra ssh-agent đã chạy chưa (xem 6.2)

9.4 Cảnh báo thay đổi host key

Nếu thấy: WARNING: REMOTE HOST IDENTIFICATION HAS CHANGED! 1. So sánh dấu vân mới với thông tin chính thức từ GitLab 2. Nếu hợp lệ, xóa bản ghi cũ: ssh-keygen -R gitlab.com 3. Kết nối lại và xác nhận fingerprint mới

9.5 Quyền truy cập file khóa quá rộng

Linux / macOS:

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

Windows: Chuột phải file private key → Properties → Security → Advanced → Disable inheritance → Chỉ giữ quyền "Full control" cho user hiện tại.

9.6 Không kết nối được với GitLab tự quản

Trên server GitLab, kiểm tra:

getent passwd git

Đầu ra phải trỏ về thư mục shell của GitLab (thường là /var/opt/gitlab/gitlab-shell). Đảm bảo sshd_config có:

PubkeyAuthentication yes

> Với bản cài Omnibus, không chỉnh sửa thủ công file ~git/.ssh/authorized_keys.

9.7 Quy trình luân chuyển khóa

1. Kiểm tra thời gian sử dụng gần nhất và hạn trên GitLab 2. Tạo khóa mới → tải lên → cập nhật IdentityFile cục bộ → kiểm thử → xóa khóa cũ trên GitLab → xóa private key cũ

10. Thực hành bảo mật tốt

	Nguyên tắc	Lý do
✅	Luôn đặt passphrase cho private key	Kết hợp agent, trải nghiệm vẫn mượt
✅	Mỗi thiết bị dùng một khóa riêng	Dễ thu hồi khi mất thiết bị
✅	Đặt hạn sử dụng cho khóa	Buộc luân chuyển định kỳ
✅	Ưu tiên Ed25519	Tránh thuật toán yếu
❌	Không đồng bộ private key lên cloud/chat/Git	Rò rỉ = mất an toàn
❌	Không chia sẻ khóa giữa nhiều người	Không thể truy vết hành động cá nhân
❌	Không thêm private key vào agent trên máy công cộng	Có thể để lại dữ liệu nhạy cảm