3.6 KiB
Windows and WSL Credential Setup
Use the environment where Git executes. Read credential persistence before any authentication attempt or configuration change.
Native Windows
Verify Git and the selected credential helper by running their version commands. Reuse a working GCM installation for the GCM/PAT path; do not install or upgrade it for an ordinary update. When that path is needed and no working installation exists, use Git for Windows with GCM or the official GCM installer. A feature-specific upgrade is permitted only when the need and task authorization are established.
GCM normally uses Windows Credential Manager. Inspect the effective helper chain and the site-specific credentialStore, namespace, username, and path policy. Do not blindly run git-credential-manager configure, remove unrelated helpers, or enter a PAT while a plaintext helper is active for this site. An earlier generic store can remain configured for other sites if the complete chain for this site excludes it.
When authorized and needed, configure only the target site's helper sequence with an empty reset followed by manager, set credential.<site>.credentialStore to wincredman, and set the site username or useHttpPath only when the intended account and sharing policy are clear. Preserve other sites and existing records; check for later system, include, user, and repository overrides. Do not assume git config --get-urlmatch shows the full helper chain.
For an unambiguous old plaintext Git credential-store entry, the migration script in credential persistence can create a separate Windows namespace and preserve the old file. Verify the credential against the server before changing the site's namespace. If the old credential is already in Windows Credential Manager, reuse it if valid. If it is rejected, diagnose first; use a fresh namespace for any necessary interactive reauthorization so the old record remains.
WSL
Choose deliberately between Linux GCM with a Linux store and the installed Windows GCM executable with Windows Credential Manager. WSL is a separate Git environment even when it uses a Windows vault. Inspect the actual GCM path and quoting; do not guess paths or replace all global helpers. A Windows-backed GCM setup requires a suitable Windows user session. Verify it from the same WSL context in which Git will run.
Local authentication
For OIDC users, follow the browser OAuth and Windows vault flow in credential persistence when the site supports it. No local Gitea password or PAT is needed for that flow. The standard Windows wincred helper can fail to save access and refresh tokens together when their UTF-16 representation exceeds the vault's blob limit; the bundled isolated vault helper addresses this without a plaintext fallback. Validate account identity, readback, helper order, and refresh support before relying on it.
When a PAT is required, the user enters the confirmed Gitea username and an existing suitable PAT in a trusted prompt, or creates a new least-privilege PAT only when needed. Never ask for a PAT in chat, command arguments, environment variables, URLs, logs, or files. Inspect remote URLs without displaying embedded credentials. Keep TLS verification enabled and configure the organization's trusted CA if necessary.
References: GCM installation, credential stores, and WSL configuration.