Authentication failures when cloning GitLab repositories in Visual Studio Code typically stem from misconfigured credential helpers or expired personal access tokens. This guide provides a systematic approach to diagnosing and resolving these issues by verifying token scopes, resetting Git configuration, and ensuring proper HTTPS versus SSH protocol selection.
Understanding the Authentication Failure
When Visual Studio Code attempts to clone a repository via HTTPS, it relies on the underlying Git installation to handle credentials. If you receive an error such as "HTTP Basic: Access denied" or "fatal: Authentication failed," Git is unable to verify your identity with GitLab's servers. This often occurs because the stored credentials are outdated, incorrect, or lack the necessary permissions. Unlike web browsers that maintain persistent sessions, command-line tools like Git require explicit, valid tokens for every operation unless a credential helper is correctly configured.
The most common cause is the use of a password instead of a Personal Access Token (PAT). GitLab deprecated password authentication for Git operations several years ago. If you are entering your account password into VSCode's credential prompt, the operation will fail. You must generate a PAT with appropriate scopes and use that string in place of your password. Additionally, network proxies or firewall settings may interfere with the authentication handshake, though this is less common than credential errors.
Generating a Valid Personal Access Token
Before troubleshooting VSCode, ensure you have a valid token generated within GitLab. Navigate to your user settings and select
Access Tokens. Create a new token with the
read_repository scope for private repositories or
write_repository if you plan to push changes. Copy the generated token immediately, as it will not be displayed again.
Store this token securely. When prompted by VSCode during the clone process, enter your username followed by the token as the password. For example, if your GitLab username is
john_doe, use
john_doe as the username and the long alphanumeric string as the password. Do not include quotes around the token. If you are using SSH instead of HTTPS, you do not need a token; instead, you must configure your SSH keys properly. For more details on SSH connectivity problems, refer to our article on
SSH Connection Issues in VSCode.
Clearing Stored Credentials
If you previously entered incorrect credentials, Git may cache them, causing subsequent attempts to fail automatically without prompting you for new input. To resolve this, you must clear the cached credentials from your system. The method depends on your operating system.
On Windows, open the Credential Manager and look under
Windows Credentials for entries related to
git:https://gitlab.com or your specific GitLab instance URL. Delete these entries. On macOS, open Keychain Access and search for
git or your GitLab domain, then remove the relevant login items. On Linux, check your desktop keyring or use the terminal command
git credential-manager erase if you are using Git Credential Manager. After clearing the cache, attempt to clone the repository again. VSCode should now prompt you for fresh credentials.
Configuring Git Credential Helper
To avoid manual entry every time, configure a credential helper. In VSCode, open the integrated terminal and run
git config --global credential.helper store. This saves your credentials in plain text in your global Git configuration file. While convenient, this is less secure than using OS-specific helpers like
osxkeychain on macOS or
manager-core on Windows. Alternatively, use
git config --global credential.helper osxkeychain for macOS users to leverage the native Keychain.
Verify the configuration by running
git config --list --show-origin. Ensure that no conflicting helper settings override your choice. If you recently switched between HTTPS and SSH, ensure your remote URL is correct. Run
git remote -v inside any existing repository to check the URL format. It should start with
https:// for token-based auth or
git@ for SSH.
Verifying Repository Permissions
Sometimes the issue is not authentication but authorization. Even with a valid token, you cannot clone a repository if the token does not have the required scope or if the project visibility settings prevent access. Log in to GitLab in your browser and navigate to the repository. Check the project settings to confirm that the token's owner has at least the
Reporter role for private projects.
If you are part of a group, ensure that the token was generated while you were logged into the correct account. Users with multiple accounts on GitLab may accidentally generate a token on one account and try to use it with another. Double-check the user profile associated with the token. For broader context on getting started with development environments, see
Getting Started with VSCode.
Testing the Connection
After applying these fixes, test the connection outside of VSCode to isolate the issue. Open a standalone terminal and run
git ls-remote https://gitlab.com/username/repo.git. If this succeeds, the problem is likely within VSCode's configuration. If it fails, the issue is with your Git setup or network. Clear VSCode's extension host cache by restarting the application or disabling and re-enabling the Git extension.
Ensure that your VSCode version is up to date. Older versions may have bugs related to newer Git protocols. Update VSCode through the help menu and restart. If problems persist, consider switching to SSH authentication entirely, which bypasses HTTP credential prompts altogether. This involves adding your public SSH key to GitLab and configuring your local SSH client.
Frequently Asked Questions
Why does VSCode still ask for my password after I cleared the cache?
VSCode may be using a different credential helper than the one you cleared. Verify which helper is active by checking your Git configuration. Switching to a system-level helper like
osxkeychain or
manager can resolve inconsistencies between manual clears and automated storage.
Can I use my GitLab password instead of a token?
No, GitLab requires Personal Access Tokens for all Git operations. Password authentication was removed to enhance security. Using a password will always result in an authentication failure. Generate a token with the necessary scopes and use it in place of the password.
How do I switch from HTTPS to SSH in VSCode?
Open the command palette and select
Git: Clone. Choose the SSH URL provided by GitLab instead of the HTTPS link. Ensure your SSH key is added to the
~/.ssh/config file and uploaded to GitLab. This eliminates the need for credential prompts entirely.
What if I get a certificate error during cloning?
Certificate errors usually indicate a network proxy or firewall issue. Verify that your organization's SSL certificates are trusted by your system. You can temporarily disable SSL verification for testing by running
git config --global http.sslVerify false, but this is not recommended for production environments.
Does VSCode cache Git credentials differently than the terminal?
VSCode uses the same Git credential helpers as the terminal. However, it may trigger credential prompts more frequently due to its event-driven nature. Clearing the system-wide credential store affects both VSCode and the terminal equally.