Bitbucket App Password Deprecated: Cách Fix Lỗi Git Pull/Git Push Bằng API Token

Một ngày bình thường, bạn SSH vào server staging hoặc production để deploy code:

cd /var/www/project
git pull

Nhưng thay vì pull code mới nhất, terminal trả về lỗi:

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

Hoặc đôi khi chỉ thấy:

fatal: Authentication failed for 'https://bitbucket.org/workspace/repo.git/'

Trường hợp khác, bạn vẫn pull được nhưng khi git push thì lỗi:

git push origin main
fatal: Authentication failed

Nguyên nhân thường gặp là project đang dùng Bitbucket App Password cũ để xác thực Git qua HTTPS. Bitbucket đã chuyển dần sang cơ chế API Token có scope, vì vậy App Password cũ có thể không còn hoạt động.

Bài viết này sẽ hướng dẫn cách kiểm tra lỗi và xử lý theo nhiều cách khác nhau, tùy trường hợp bạn đang dùng local machine, Sourcetree, server deploy, CI/CD hay script tự động.

1. Vấn đề là gì?

Lỗi thường gặp

Khi chạy git pull, git clone hoặc git push, bạn có thể gặp một trong các lỗi sau:

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

fatal: Authentication failed for 'https://bitbucket.org/<workspace>/<repo>.git/'

remote: Invalid username or password
fatal: Authentication failed

Những lỗi này thường xuất hiện khi Git đang dùng credential cũ, App Password cũ, token sai scope hoặc account tạo token không có quyền truy cập repository.

2. Nguyên nhân chính

App Password đã bị deprecated

Trước đây, Bitbucket cho phép dùng App Password thay cho mật khẩu tài khoản Atlassian khi thao tác Git qua HTTPS.

Ví dụ:

git clone https://username@bitbucket.org/workspace/repo.git

Khi Git hỏi password, bạn nhập App Password.

Tuy nhiên hiện tại Bitbucket đã chuyển sang API Token with scopes. Nghĩa là bạn cần tạo token mới và cấp đúng quyền cần thiết.

Token cần đúng scope

Nếu bạn chỉ cần pull code, token cần quyền đọc repository:

read:repository:bitbucket

Nếu bạn cần push code, token cần thêm quyền ghi repository:

write:repository:bitbucket

Nếu token chỉ có các scope như read:me hoặc read:account, Git vẫn không thể pull/push repository.

3. Ai sẽ bị ảnh hưởng?

Dev dùng local machine

Nếu bạn clone/pull/push repo Bitbucket qua HTTPS trên máy cá nhân, bạn có thể gặp lỗi authentication khi credential cũ không còn hợp lệ.

Server staging/production

Nếu server deploy đang chạy:

git pull origin main

và trước đó dùng App Password, quá trình deploy có thể bị lỗi.

CI/CD pipeline

Các hệ thống như Jenkins, GitHub Actions, GitLab CI, Bitbucket Pipelines hoặc script deploy nội bộ có thể fail nếu đang dùng App Password cũ.

Composer/private package

Nếu project PHP dùng Composer để kéo private package từ Bitbucket, Composer cũng có thể lỗi authentication nếu credential Bitbucket cũ không còn hoạt động.

4. Hướng dẫn tạo Bitbucket API Token đúng cách

Bước 1: Vào Atlassian Account Settings

Đăng nhập bằng account Atlassian có quyền truy cập repository.

Đi tới: https://id.atlassian.com/manage-profile/security

Atlassian Account Settings → Security

Bước 2: Mở phần API Tokens

Trong phần Security, tìm mục:

Create and manage API tokens

Nhấn vào để mở trang quản lý API Token.

Bước 3: Chọn Create API token with scopes

Chọn:

Create API token with scopes

Không nên tạo token kiểu quá rộng quyền nếu không cần.

Bước 4: Nhập name và ngày hết hạn token (tối đa 1 năm) và chọn App Bitbucket

Bước 5: Chọn scope phù hợp

Nếu server hoặc máy local chỉ cần clone/pull code:

read:repository:bitbucket

Nếu cần push code:

read:repository:bitbucket
write:repository:bitbucket

Không tick các quyền mạnh nếu không cần:

admin:repository:bitbucket
delete:repository:bitbucket

Nguyên tắc quan trọng:

Chỉ cấp quyền tối thiểu cần thiết. Nếu chỉ pull code thì không cấp quyền write, admin hoặc delete.

Bước 6: Copy token và lưu an toàn

Sau khi tạo xong, copy API Token ngay.

Lưu ý:

• Token thường chỉ hiển thị một lần.

• Không gửi token qua chat công khai.

• Không đưa token vào source code.

• Không commit token lên Git.

• Nên lưu token trong password manager hoặc secret manager.

5. Cách kiểm tra remote hiện tại

Trước khi sửa, kiểm tra remote:

git remote -v

Ví dụ kết quả:

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

Nếu remote đang dùng username cũ hoặc credential cũ, bạn cần đổi sang format dùng API Token.

6. Cách giải quyết 1: Dùng API Token nhưng không nhúng token vào remote URL

Đây là cách nên ưu tiên nếu bạn thao tác trên máy cá nhân hoặc server có thể nhập password thủ công.

Cập nhật remote:

git remote set-url origin https://x-bitbucket-api-token-auth@bitbucket.org/<workspace>/<repo>.git

Ví dụ:

git remote set-url origin https://x-bitbucket-api-token-auth@bitbucket.org/anhtran/atdevblog.git

Sau đó chạy:

git pull

Hoặc nếu cần push:

git push origin main

Khi Git hỏi password:

Password for 'https://x-bitbucket-api-token-auth@bitbucket.org':

Dán API Token vào.

Khi nào nên dùng cách này?

Cách này phù hợp khi:

• Bạn thao tác trên local machine.

• Bạn không muốn token hiển thị trong git remote -v.

• Bạn muốn bảo mật hơn so với việc nhúng token trực tiếp vào URL.

• Git có thể hiện prompt hỏi password.

Ưu điểm

• An toàn hơn.

• Token không nằm trực tiếp trong remote URL.

• Giảm nguy cơ lộ token qua .git/config.

Nhược điểm

• Nếu Git hoặc Sourcetree bị kẹt credential cũ, có thể vẫn lỗi.

• Nếu server deploy tự động không có prompt nhập password, cách này có thể không phù hợp.

7. Cách giải quyết 2: Nhúng API Token trực tiếp vào remote URL

Trong một số trường hợp, Git hoặc Sourcetree không hiện prompt nhập password, hoặc máy đang bị kẹt credential cũ. Khi đó bạn có thể tạm thời dùng cách nhúng token vào URL.

git remote set-url origin https://x-bitbucket-api-token-auth:<TOKEN>@bitbucket.org/<workspace>/<repo>.git

Ví dụ:

git remote set-url origin https://x-bitbucket-api-token-auth:<TOKEN>@bitbucket.org/anhtran/atdevblog.git

Sau đó chạy:

git push origin main

Hoặc:

git pull

Khi nào nên dùng cách này?

Cách này phù hợp khi:

• Bạn cần fix nhanh.

• Git không hiện prompt nhập password.

• Sourcetree vẫn dùng credential cũ.

• Bạn đang cần push/pull gấp để deploy hoặc release.

Vì sao cách này hoạt động?

Vì token đã được truyền trực tiếp trong URL, Git không cần hỏi password nữa.

Rủi ro bảo mật

Không nên dùng lâu dài vì token có thể bị lộ qua:

git remote -v

Hoặc trong file:

.git/config

Ngoài ra token có thể bị lưu trong:

• Shell history

• Log deploy

• Backup server

• Screenshot terminal

• Tài liệu nội bộ

Sau khi fix xong nên làm gì?

Sau khi push/pull thành công, nên đổi remote lại dạng không chứa token:

git remote set-url origin https://x-bitbucket-api-token-auth@bitbucket.org/<workspace>/<repo>.git

Ví dụ:

git remote set-url origin https://x-bitbucket-api-token-auth@bitbucket.org/anhtran/atdevblog.git

Sau đó kiểm tra:

git remote -v

Nếu không còn thấy token trong URL là ổn.

8. Cách giải quyết 3: Xóa credential cũ trên máy

Nếu bạn đã đổi remote đúng nhưng vẫn bị lỗi:

fatal: Authentication failed

có thể Git đang dùng credential cũ đã lưu trong máy.

Kiểm tra credential helper

git config --global credential.helper

Nếu dùng macOS, thường credential được lưu trong Keychain.

Nếu dùng Windows, có thể nằm trong Git Credential Manager.

Trên macOS

Mở:

Keychain Access

Tìm các entry liên quan đến:

bitbucket.org

Xóa credential cũ, sau đó chạy lại:

git pull

Git sẽ hỏi password lại. Lúc này dán API Token mới.

Trên Windows

Mở:

Credential Manager → Windows Credentials

Tìm credential liên quan đến Bitbucket hoặc bitbucket.org, sau đó remove.

Với Sourcetree

Nếu dùng Sourcetree, bạn nên kiểm tra lại phần account hoặc authentication trong Sourcetree.

Có thể cần:

• Remove account Bitbucket cũ.

• Add lại account.

• Dùng API Token mới.

• Kiểm tra remote URL trong repository settings.

9. Cách giải quyết 4: Dùng SSH Key thay vì HTTPS

Nếu bạn quản lý server deploy lâu dài, SSH key thường là lựa chọn ổn định hơn so với HTTPS token.

Remote SSH thường có dạng:

git@bitbucket.org:<workspace>/<repo>.git

Đổi remote sang SSH:

git remote set-url origin git@bitbucket.org:<workspace>/<repo>.git

Ví dụ:

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

Kiểm tra:

git remote -v

Sau đó test:

git pull

Khi nào nên dùng SSH?

Nên cân nhắc SSH nếu:

• Server deploy lâu dài.

• Không muốn lưu personal token trên server.

• Muốn tách quyền deploy với tài khoản cá nhân.

• Dự án có quy trình DevOps rõ ràng.

Lưu ý

Bạn cần tạo SSH key trên server và add public key vào Bitbucket đúng chỗ. Nếu dùng SSH key cá nhân, cần quản lý quyền cẩn thận. Nếu dùng deploy key/repository key, nên giới hạn quyền theo repository.

10. Cách giải quyết 5: Dùng Repository Access Token cho server deploy hoặc CI/CD

Nếu mục tiêu chỉ là cho một server, script hoặc CI/CD truy cập một repository cụ thể, bạn có thể cân nhắc Repository Access Token.

Loại token này không gắn trực tiếp với tài khoản cá nhân theo cùng cách API Token cá nhân. Nó phù hợp hơn cho automation, CI/CD hoặc script chỉ cần quyền trong phạm vi một repository.

Khi nào nên dùng Repository Access Token?

Nên dùng khi:

• Chỉ cần deploy một repository cụ thể.

• Không muốn dùng token cá nhân.

• Muốn quản lý quyền theo repository.

• Có nhiều server hoặc pipeline cần truy cập repo.

• Muốn dễ revoke khi không dùng nữa.

Gợi ý quyền

Nếu chỉ deploy bằng git pull, chỉ cấp quyền read repository.

Nếu pipeline cần push tag, push version hoặc update code, mới cân nhắc quyền write.

11. So sánh nhanh các cách xử lý

12. Lỗi thường gặp và cách xử lý

Lỗi 1: Token không có quyền repository

Triệu chứng:

fatal: Authentication failed

Nguyên nhân:

Bạn tạo token nhưng không tick:

read:repository:bitbucket

Cách xử lý:

Tạo lại token có scope repository.

Nếu cần push, thêm:

write:repository:bitbucket

Lỗi 2: Chỉ tick read:me hoặc read:account

Các scope này chỉ cho phép đọc thông tin account, không đủ để Git pull/push repository.

Cách xử lý:

Tạo token mới và chọn đúng repository scope.

Lỗi 3: Tạo token bằng account không có quyền vào repo

API Token chỉ có quyền tương ứng với account tạo token.

Nếu account không vào được repository trên Bitbucket bằng trình duyệt, token cũng không pull/push được.

Cách xử lý:

• Kiểm tra account có quyền repo chưa.

• Nhờ admin add quyền vào workspace/repository.

• Tạo token bằng account có quyền phù hợp.

Lỗi 4: Copy thiếu token

Token thường dài và chỉ hiển thị một lần. Nếu copy thiếu ký tự hoặc thừa khoảng trắng, Git sẽ báo authentication failed.

Cách xử lý:

• Revoke token cũ.

• Tạo token mới.

• Copy cẩn thận.

• Lưu vào password manager.

Lỗi 5: Nhầm giữa API Token cá nhân và Repository Access Token

API Token cá nhân thường dùng với:

x-bitbucket-api-token-auth

Repository Access Token là loại token khác, phù hợp cho repo cụ thể, CI/CD hoặc deploy script.

Cách xử lý:

Xác định rõ bạn đang dùng loại token nào và dùng đúng hướng dẫn tương ứng.

Lỗi 6: Token có read nhưng không push được

Nếu pull được nhưng push lỗi, nguyên nhân thường là token chỉ có quyền read.

Cách xử lý:

Tạo token mới có thêm:

write:repository:bitbucket

Sau đó thử lại:

git push origin main

13. Checklist nhanh cho dev và DevOps

Trước khi deploy hoặc fix lỗi Bitbucket authentication, hãy kiểm tra:

git remote -v

Nếu dùng API Token cá nhân qua HTTPS, remote nên có dạng:

https://x-bitbucket-api-token-auth@bitbucket.org/<workspace>/<repo>.git

Nếu cần fix nhanh bằng URL có token, nhớ đổi lại sau khi xong:

git remote set-url origin https://x-bitbucket-api-token-auth@bitbucket.org/<workspace>/<repo>.git

Kiểm tra token có scope:

read:repository:bitbucket

Nếu cần push:

write:repository:bitbucket

Không cấp quyền nếu không cần:

admin:repository:bitbucket
delete:repository:bitbucket

Không hardcode token vào source code.

Không commit token lên Git.

Không lưu token trong README hoặc script public.

Không chụp màn hình terminal có token thật.

Với server deploy lâu dài, nên cân nhắc:

• SSH Key

• Repository Access Token

• CI/CD Secret Variable

• Secret Manager

14. Kết luận

Nếu bạn gặp lỗi:

remote: App passwords are deprecated and must be replaced with API tokens.
fatal: unable to access ... The requested URL returned error: 410

hoặc:

fatal: Authentication failed

thì nguyên nhân rất có thể là Bitbucket App Password cũ không còn phù hợp hoặc token hiện tại chưa đúng quyền.

Cách xử lý nhanh nhất là tạo Bitbucket API Token có scope đúng:

read:repository:bitbucket

Nếu cần push:

write:repository:bitbucket

Sau đó cập nhật remote theo một trong các cách phù hợp.

Cách an toàn hơn:

git remote set-url origin https://x-bitbucket-api-token-auth@bitbucket.org/<workspace>/<repo>.git

Cách fix nhanh khi Git không hỏi password:

git remote set-url origin https://x-bitbucket-api-token-auth:<TOKEN>@bitbucket.org/<workspace>/<repo>.git

Nhưng sau khi fix xong, nên đổi lại remote để không lưu token trực tiếp trong URL.

Nguyên tắc cuối cùng cần nhớ:

Chỉ cấp quyền tối thiểu cần thiết. Server chỉ pull code thì chỉ cần quyền read. Chỉ cấp write khi thật sự cần push.

CTA

Nếu bạn đang quản lý nhiều project dùng Bitbucket, hãy kiểm tra lại toàn bộ server, CI/CD và script deploy đang dùng HTTPS. Việc cập nhật credential sớm sẽ giúp tránh lỗi deploy bất ngờ khi cần release hoặc hotfix production.