Bitbucket App Password Deprecated: Cách Setup SSH Key Để Giải Quyết Git Push/Git Pull

Nếu bạn đang dùng Bitbucket qua HTTPS, có thể một ngày bạn chạy:

git pull

hoặc:

git push origin main

và gặp lỗi:

remote: App passwords are deprecated and must be replaced with API tokens.
fatal: unable to access 'https://bitbucket.org/anhtran/atdevblog.git/': The requested URL returned error: 410

Hoặc:

fatal: Authentication failed

Nguyên nhân thường gặp là project vẫn đang dùng Bitbucket App Password cũ hoặc credential HTTPS cũ đã lưu trong máy. Cách xử lý nhanh là chuyển sang API Token, nhưng nếu bạn muốn setup ổn định hơn cho máy dev cá nhân, đặc biệt là MacBook dùng thường xuyên để push/pull code, thì SSH Key là một lựa chọn rất sạch và tiện.

Bài viết này hướng dẫn cách setup SSH Key cho Bitbucket trên MacBook, giải thích rõ từng command, chạy lệnh ở đâu, kết quả như thế nào là đúng, và Windows có gì khác so với macOS.

1. Khi nào nên dùng SSH Key thay vì HTTPS/API Token?

Bạn nên dùng SSH Key nếu:

• Bạn thường xuyên push/pull code từ máy cá nhân.

• Bạn không muốn mỗi lần Git lại hỏi password/API Token.

• Bạn không muốn nhúng token trực tiếp vào Git remote URL.

• Bạn muốn tránh lỗi Bitbucket App Password deprecated khi dùng HTTPS.

• Bạn muốn setup Git gọn, ổn định, ít phụ thuộc credential cache.

Ví dụ remote HTTPS cũ:

https://bitbucket.org/anhtran/atdevblog.git

Sau khi đổi sang SSH, remote sẽ là:

git@bitbucket.org:anhtran/atdevblog.git

Từ đó, Git sẽ xác thực bằng SSH Key thay vì hỏi password hoặc API Token.

2. Ví dụ repository trong bài

Trong bài này, ví dụ repo là:

anhtran/atdevblog.git

Remote HTTPS:

https://bitbucket.org/anhtran/atdevblog.git

Remote SSH:

git@bitbucket.org:anhtran/atdevblog.git

Bạn chỉ cần thay anhtran/atdevblog.git bằng workspace/repository thực tế của bạn.

3. Setup SSH Key trên MacBook

Bước 1: Mở Terminal

Trên MacBook, mở app:

Terminal

Bạn có thể chạy các lệnh tạo SSH key ở bất kỳ thư mục nào, vì đường dẫn ~/.ssh/... luôn trỏ về thư mục SSH trong Home của user hiện tại.

Ví dụ:

~/.ssh/bitbucket_atdevblog

nghĩa là file key sẽ nằm tại:

/Users/<ten-user-cua-ban>/.ssh/bitbucket_atdevblog

Bạn không cần phải cd vào project ở bước tạo SSH key.

Bước 2: Tạo SSH Key

Chạy lệnh:

ssh-keygen -t ed25519 -C "anhtran-local-bitbucket" -f ~/.ssh/bitbucket_atdevblog

Giải thích từng phần:

ssh-keygen

Lệnh dùng để tạo SSH key.

-t ed25519

Chọn loại key là Ed25519. Đây là loại key hiện đại, gọn và được khuyến nghị sử dụng phổ biến hiện nay.

-C "anhtran-local-bitbucket"

Phần comment để bạn dễ nhận biết key này dùng cho mục đích gì. Bạn có thể đặt là:

"anhtran-macbook-bitbucket"

hoặc:

"atdevblog-local-bitbucket"

-f ~/.ssh/bitbucket_atdevblog

Chỉ định tên file key sẽ được tạo. Trong ví dụ này, private key sẽ nằm tại:

~/.ssh/bitbucket_atdevblog

và public key sẽ nằm tại:

~/.ssh/bitbucket_atdevblog.pub

Khi được hỏi passphrase:

Enter passphrase (empty for no passphrase):

Bạn có thể nhập passphrase để tăng bảo mật, hoặc để trống nếu muốn thao tác Git nhanh hơn trên máy cá nhân. Nếu để trống, cần đảm bảo máy cá nhân được bảo vệ tốt bằng mật khẩu, Touch ID hoặc FileVault.

Bước 3: Copy public key

Sau khi tạo key xong, chạy:

cat ~/.ssh/bitbucket_atdevblog.pub

Kết quả sẽ có dạng:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxx anhtran-local-bitbucket

Copy toàn bộ dòng này.

Lưu ý rất quan trọng:

• Chỉ copy file .pub.

• Không copy private key.

• Không gửi file ~/.ssh/bitbucket_atdevblog cho người khác.

• Không commit private key lên Git.

Public key là file được phép đưa lên Bitbucket. Private key phải luôn nằm an toàn trên máy của bạn.

Bước 4: Add SSH Key vào Bitbucket

Vào Bitbucket trên trình duyệt:

Personal Bitbucket settings → Security → SSH keys → Add key

Sau đó nhập:

Label: MacBook - atdevblog

Dán public key vừa copy vào ô key.

Ví dụ:

ssh-ed25519 AAAAC3NzaC1lZDI1NTE5AAAAIxxxxxxxxxxxxxxxx anhtran-local-bitbucket

Sau đó nhấn:

Add key

Bước 5: Tạo hoặc sửa file SSH config

Tiếp theo, bạn cần tạo file config để máy biết khi kết nối tới Bitbucket thì dùng đúng SSH key nào.

Lệnh:

nano ~/.ssh/config

Nếu file chưa tồn tại, lệnh nano ~/.ssh/config sẽ tạo file mới.

Nếu file đã tồn tại, lệnh này sẽ mở file hiện tại để bạn chỉnh sửa.

Bước 6: Thêm cấu hình SSH cho Bitbucket

Thêm đoạn sau vào file:

Host bitbucket.org
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/bitbucket_atdevblog
  IdentitiesOnly yes

Giải thích từng dòng:

Host bitbucket.org

Đây là tên host bạn sẽ kết nối. Khi Git gặp remote dạng:

git@bitbucket.org:anhtran/atdevblog.git

SSH sẽ dùng block cấu hình này.

HostName bitbucket.org

Địa chỉ server thật mà SSH sẽ kết nối tới. Trong trường hợp này là Bitbucket.

User git

User SSH dùng để kết nối Bitbucket luôn là git. Đây không phải username Bitbucket cá nhân của bạn.

IdentityFile ~/.ssh/bitbucket_atdevblog

Chỉ định private key cần dùng khi kết nối tới Bitbucket.

Trong ví dụ này, SSH sẽ dùng file:

~/.ssh/bitbucket_atdevblog

IdentitiesOnly yes

Yêu cầu SSH chỉ dùng đúng key đã chỉ định trong IdentityFile, tránh việc SSH thử quá nhiều key khác và gây lỗi xác thực.

Sau khi thêm xong, nhấn:

Control + O
Enter
Control + X

để lưu và thoát khỏi nano.

Bước 7: Set permission cho file SSH

Chạy:

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

Mục đích là đảm bảo SSH key không bị để quyền quá rộng.

Nếu quyền file private key quá mở, SSH có thể từ chối sử dụng key.

Bước 8: Test kết nối SSH tới Bitbucket

Chạy:

ssh -T git@bitbucket.org

Kết quả như thế nào là OK?

Nếu thành công, bạn có thể thấy thông báo gần giống:

authenticated via ssh key.
You can use git to connect to Bitbucket. Shell access is disabled

Hoặc nội dung tương tự báo rằng bạn đã xác thực thành công bằng SSH key.

Lưu ý:

Shell access is disabled

là bình thường. Bitbucket chỉ cho phép dùng SSH để Git clone/pull/push, không cho bạn mở shell trực tiếp như SSH vào server Linux.

Nếu thấy dòng xác thực thành công, nghĩa là SSH key đã được setup đúng.

4. Đổi remote local sang SSH

Sau khi SSH key đã hoạt động, bạn cần đổi remote của project từ HTTPS sang SSH.

Bước 1: Đi vào thư mục project local

Lệnh này phải chạy trong thư mục project Git trên máy bạn.

Ví dụ:

cd ~/Projects/atdevblog

Hoặc thư mục thực tế của bạn:

cd /path/to/your/project

Kiểm tra có đúng là Git repo không:

git status

Nếu thấy thông tin branch hiện tại, ví dụ:

On branch main

nghĩa là bạn đang đứng đúng trong project Git.

Bước 2: Kiểm tra remote hiện tại

Chạy:

git remote -v

Nếu đang dùng HTTPS, bạn sẽ thấy dạng:

origin  https://bitbucket.org/anhtran/atdevblog.git (fetch)
origin  https://bitbucket.org/anhtran/atdevblog.git (push)

Bước 3: Đổi remote sang SSH

Chạy:

git remote set-url origin git@bitbucket.org:anhtran/atdevblog.git

Sau đó kiểm tra lại:

git remote -v

Kết quả đúng sẽ là:

origin  git@bitbucket.org:anhtran/atdevblog.git (fetch)
origin  git@bitbucket.org:anhtran/atdevblog.git (push)

Nếu đã thấy git@bitbucket.org:... nghĩa là remote đã chuyển sang SSH thành công.

5. Test git pull và git push

Test git pull

Chạy:

git pull origin main

Nếu đã mới nhất, kết quả có thể là:

Already up to date.

Nếu có code mới, Git sẽ hiển thị thông tin update file/commit.

Cả hai trường hợp đều là OK miễn là không còn lỗi authentication.

Test git push

Nếu bạn có quyền push vào repo, chạy:

git push origin main

Kết quả như thế nào là OK?

Nếu không có gì mới để push, bạn có thể thấy:

Everything up-to-date

Nếu có commit mới, kết quả có thể hiển thị:

Enumerating objects: ...
Counting objects: ...
Compressing objects: ...
Writing objects: ...
To bitbucket.org:anhtran/atdevblog.git
old_commit..new_commit main -> main

Nếu thấy push lên bitbucket.org:anhtran/atdevblog.git thành công và không còn Authentication failed, nghĩa là setup SSH đã OK.

6. Windows làm có khác gì so với macOS không?

Có khác một chút, nhưng logic chính vẫn giống nhau.

Cùng một flow:

Tạo SSH key → Add public key vào Bitbucket → Tạo SSH config → Test ssh -T → Đổi remote sang SSH → Test pull/push

Điểm khác chủ yếu nằm ở terminal, đường dẫn file và cách mở file config.

Trên Windows nên dùng terminal nào?

Bạn có thể dùng một trong các lựa chọn sau:

• Git Bash

• PowerShell

• Windows Terminal

• Terminal tích hợp trong VS Code

Nếu bạn đã cài Git for Windows, dùng Git Bash thường dễ nhất vì command gần giống macOS/Linux.

Tạo SSH key bằng Git Bash

Mở Git Bash và chạy:

ssh-keygen -t ed25519 -C "anhtran-windows-bitbucket" -f ~/.ssh/bitbucket_atdevblog

Trên Git Bash, dấu ~ vẫn trỏ về thư mục home của user.

Thường tương ứng với:

C:\Users\<YourUser>\.ssh\

Ví dụ file private key:

C:\Users\AnhTran\.ssh\bitbucket_atdevblog

Public key:

C:\Users\AnhTran\.ssh\bitbucket_atdevblog.pub

Copy public key:

cat ~/.ssh/bitbucket_atdevblog.pub

Sau đó add vào Bitbucket giống như trên Mac:

Personal Bitbucket settings → Security → SSH keys → Add key

Tạo SSH config

Nếu dùng Git Bash, bạn có thể chạy:

nano ~/.ssh/config

Nếu máy không có nano, dùng Notepad:

notepad ~/.ssh/config

Hoặc mở trực tiếp file:

C:\Users\<YourUser>\.ssh\config

Thêm nội dung:

Host bitbucket.org
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/bitbucket_atdevblog
  IdentitiesOnly yes

Ý nghĩa từng dòng giống hệt macOS:

• Host bitbucket.org: cấu hình cho kết nối tới Bitbucket.

• HostName bitbucket.org: server thật cần kết nối.

• User git: user SSH của Bitbucket là git.

• IdentityFile ~/.ssh/bitbucket_atdevblog: key sẽ dùng để xác thực.

• IdentitiesOnly yes: chỉ dùng đúng key này.

Test SSH

Trong Git Bash, chạy:

ssh -T git@bitbucket.org

Kết quả OK cũng tương tự macOS:

authenticated via ssh key.
You can use git to connect to Bitbucket. Shell access is disabled

Nếu lần đầu kết nối, Windows/Git Bash có thể hỏi:

Are you sure you want to continue connecting (yes/no/[fingerprint])?

Nhập:

yes

Sau đó chạy lại lệnh test nếu cần.

Đổi remote sang SSH

Bước này giống hệt macOS.

Bạn cần đứng trong thư mục project Git.

Ví dụ:

cd /c/Users/AnhTran/Projects/atdevblog

Kiểm tra:

git remote -v

Đổi remote:

git remote set-url origin git@bitbucket.org:anhtran/atdevblog.git

Test pull:

git pull origin main

Test push:

git push origin main

Khác biệt quan trọng giữa Windows và macOS

7. Lỗi thường gặp khi setup SSH Key Bitbucket

Lỗi 1: Permission denied publickey

Lỗi:

git@bitbucket.org: Permission denied (publickey).
fatal: Could not read from remote repository.

Nguyên nhân có thể là:

• Chưa add public key vào Bitbucket.

• Add nhầm key.

• SSH config trỏ sai IdentityFile.

• Git đang dùng key khác.

• Account Bitbucket không có quyền vào repo.

Cách kiểm tra:

ssh -T git@bitbucket.org

Nếu test SSH chưa OK thì chưa nên test git pull/git push.

Lỗi 2: Remote vẫn là HTTPS

Nếu bạn đã setup SSH nhưng vẫn thấy lỗi App Password/API Token, có thể remote vẫn đang dùng HTTPS.

Kiểm tra:

git remote -v

Nếu vẫn thấy:

https://bitbucket.org/anhtran/atdevblog.git

hãy đổi sang SSH:

git remote set-url origin git@bitbucket.org:anhtran/atdevblog.git

Lỗi 3: Host key verification failed

Lỗi:

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

Thử chạy:

ssh -T git@bitbucket.org

Nếu hệ thống hỏi có tin tưởng host không, nhập:

yes

Sau đó test lại:

git pull origin main

Lỗi 4: Máy có nhiều SSH key

Nếu máy có nhiều key, SSH có thể dùng nhầm key.

Cách xử lý là khai báo rõ trong file:

~/.ssh/config

Nội dung:

Host bitbucket.org
  HostName bitbucket.org
  User git
  IdentityFile ~/.ssh/bitbucket_atdevblog
  IdentitiesOnly yes

Nếu vẫn lỗi, chạy debug:

ssh -vT git@bitbucket.org

Lệnh này giúp xem SSH đang dùng key nào.

Lỗi 5: Push bị denied dù SSH test OK

Nếu:

ssh -T git@bitbucket.org

đã OK nhưng:

git push origin main

vẫn lỗi permission, có thể account hoặc SSH key của bạn chỉ có quyền read repo, không có quyền write.

Cách xử lý:

• Kiểm tra quyền của account trong repository.

• Kiểm tra bạn có quyền write vào branch main không.

• Kiểm tra branch có rule/protection không.

• Thử push sang branch khác nếu project không cho push trực tiếp vào main.

8. Checklist nhanh sau khi setup thành công

Kiểm tra SSH key đã tạo:

ls -la ~/.ssh

Kiểm tra config:

cat ~/.ssh/config

Test SSH:

ssh -T git@bitbucket.org

Kết quả OK nếu thấy xác thực thành công bằng SSH key.

Kiểm tra remote:

git remote -v

Remote đúng nếu thấy:

git@bitbucket.org:anhtran/atdevblog.git

Test pull:

git pull origin main

OK nếu không còn lỗi authentication.

Test push:

git push origin main

OK nếu thấy Everything up-to-date hoặc push commit thành công.

9. Nên dùng SSH Key hay API Token?

Nếu bạn đã setup SSH Key thành công trên MacBook, đây là hướng rất ổn cho môi trường dev cá nhân.

Còn với server staging/production, không nên copy private key từ local lên server nếu không cần. Tốt hơn là tạo một SSH key riêng ngay trên server hoặc dùng Repository Access Token cho deploy.

10. Kết luận

Khi Bitbucket App Password bị deprecated, các lệnh Git qua HTTPS như:

git pull
git clone
git push

có thể gặp lỗi authentication.

Có nhiều cách xử lý, nhưng nếu bạn dùng máy cá nhân để làm việc hằng ngày, setup SSH Key là một cách sạch, ổn định và dễ duy trì.

Flow chuẩn là:

ssh-keygen -t ed25519 -C "anhtran-local-bitbucket" -f ~/.ssh/bitbucket_atdevblog
cat ~/.ssh/bitbucket_atdevblog.pub
nano ~/.ssh/config
ssh -T git@bitbucket.org
git remote set-url origin git@bitbucket.org:anhtran/atdevblog.git
git pull origin main
git push origin main

Điểm cần nhớ:

• Tạo SSH key ở local nếu bạn muốn push/pull từ máy local.

• Tạo SSH key trên server nếu server cần tự git pull để deploy.

• Không chia sẻ private key.

• Không commit private key lên Git.

• Remote SSH đúng format là:

git@bitbucket.org:anhtran/atdevblog.git

Nếu test SSH OK và git remote -v đã chuyển sang SSH, bạn có thể push/pull code mà không cần dùng App Password hoặc API Token trong remote URL nữa.

CTA

Nếu bạn đang gặp lỗi App passwords are deprecated, Authentication failed hoặc error 410 khi dùng Bitbucket, hãy kiểm tra lại Git remote ngay. Nếu bạn làm việc trên máy cá nhân, hãy cân nhắc chuyển sang SSH Key để việc push/pull code ổn định và an toàn hơn.