Resolving Sourcetree Authentication Failure When Pushing to GitHub

Problem Description

Users often encounter error messages when pushing code to GitHub with Sourcetree: remote: Invalid username or password. fatal: Authentication failed. Even after refreshing OAuth tokens in the tools and receiving confirmation of successful authentication, the issue persists, indicating interruptions in the authentication process due to caching or configuration problems.

Cause Analysis

According to Atlassian's official documentation, this is a known bug in Sourcetree versions 2.1.8 and above. The bug causes authentication information to not update or cache properly, leading to authentication failures during push operations, even when the underlying credentials are valid. This is often related to the version of embedded Git or local cache files.

Solution Steps

The primary solution involves updating embedded Git and clearing related cache files. Here are the detailed steps:

1. Open Sourcetree, navigate to Tools > Options > Git, and click Update Embedded Git. This can fix potential Git version incompatibility issues.
2. Close the Sourcetree application to ensure all processes are fully stopped.
3. Delete cache files: On Windows, delete the path AppData\Local\Atlassian\SourceTree\passwd; on Mac, delete the file ~/Library/Application Support/SourceTree/userName@STAuth-bitbucket.org and clear related entries in KeyChain Access. This helps remove old or corrupted authentication data.
4. Restart Sourcetree and reattempt the push operation. Typically, this will restore normal authentication flow.

As an alternative, using command-line Git to push code can often bypass this bug, as the command-line tool may not be affected by the same caching issues. For example, running the command git push origin live_version:live_version in the terminal might succeed.

Additional Notes

For Mac users, in addition to deleting files, it may be necessary to search and delete "login" entries related to Sourcetree in KeyChain Access to ensure thorough cache clearance. Furthermore, although the issue is not typically related to two-factor authentication, users should check account settings to rule out other potential causes. Reference other answers, such as Answer 2, provides more specific steps for Mac environments, but the core principles are similar to the Windows version.

Conclusion

By updating embedded Git and clearing cache files, users can efficiently resolve Sourcetree authentication failures. It is recommended to keep Sourcetree and Git updated to avoid similar bugs. This solution is based on an in-depth analysis of software internal mechanisms, highlighting the importance of cache management in authentication processes.