5.4 KiB
Linux GCM Setup
Use this reference when Git runs on native Linux. This includes a Linux desktop controlled from Windows through RDP, VNC, or similar software. Use the Windows reference only when Git itself runs on Windows or WSL is intentionally using the Windows GCM executable.
Identify the Session
Verify Git, GCM, the executable paths, and the configured helper:
uname -s
git --version
git-credential-manager --version
command -v git
command -v git-credential-manager
git config --show-origin --get-all credential.helper
If the GCM version command succeeds, reuse that installation. Do not install or upgrade it during an ordinary repository update.
A visible remote desktop does not guarantee that an agent or background shell inherited the desktop session. Check without printing unrelated environment values:
test -n "${DISPLAY:-}" || test -n "${WAYLAND_DISPLAY:-}"
Install When GCM Is Missing
Linux needs both GCM and an explicitly selected credential store. Use an official installation method appropriate for the distribution: the .NET global tool, a verified Debian package, or a verified release tarball. Run git-credential-manager configure afterward.
Do not download an unpinned executable from an unofficial source. Verify the release signature or checksum before installation. If the normal package needs administrator rights, ask the user to run the installation locally or use an official current-user method; never ask for an administrator password in chat.
On a Debian-based host without administrator access, a verified official .deb can be unpacked into the current user's directories. Inspect the package first and stop if its layout differs from usr/local/share/gcm-core:
gcm_package="/absolute/path/to/verified-gcm.deb"
gcm_unpack_dir=$(mktemp -d)
gcm_install_dir="${XDG_DATA_HOME:-$HOME/.local/share}/gcm-core"
gcm_bin_dir="$HOME/.local/bin"
dpkg-deb -c "$gcm_package"
test ! -e "$gcm_install_dir"
test ! -e "$gcm_bin_dir/git-credential-manager"
test ! -L "$gcm_bin_dir/git-credential-manager"
dpkg-deb -x "$gcm_package" "$gcm_unpack_dir"
test -x "$gcm_unpack_dir/usr/local/share/gcm-core/git-credential-manager"
install -d "$(dirname "$gcm_install_dir")" "$gcm_bin_dir"
cp -a "$gcm_unpack_dir/usr/local/share/gcm-core" "$gcm_install_dir"
ln -s "$gcm_install_dir/git-credential-manager" "$gcm_bin_dir/git-credential-manager"
"$gcm_bin_dir/git-credential-manager" --version
"$gcm_bin_dir/git-credential-manager" configure
Use the full executable path until $HOME/.local/bin is available on PATH. If an install directory or link already exists, inspect it and repair only the known broken installation; do not overwrite it blindly.
Choose a Credential Store
For a graphical Linux session with a working Secret Service collection:
git config --global credential.credentialStore secretservice
git-credential-manager configure
Secret Service requires a graphical session to unlock its collection. If Git runs from an agent, background shell, or terminal without access to that graphical session, configure GCM's in-memory cache only in the target repository:
git config --local credential.credentialStore cache
git config --local credential.cacheOptions "--timeout 900"
This keeps the PAT in memory for 15 minutes and leaves GCM as the Git credential helper. Do not replace it with a plaintext credential store. Do not change a working global Secret Service configuration merely because one repository is being updated from a non-graphical shell.
For persistent use without a graphical session, GCM also supports the gpg store after gpg, pass, and a key pair have been set up. Do not initialize those tools or keys as a side effect of a repository update unless the user requests it.
OIDC Web Login and Git Push
An organization may use DingTalk or another OIDC provider for the Gitea website. Treat that as the way to open the account settings and create a PAT. Unless the Gitea instance explicitly documents another Git flow, the HTTPS push still uses:
- Username: the Gitea login accepted by the instance.
- Password: a PAT with
write:repository, entered only in the user's local terminal prompt.
Run the push from an interactive terminal:
cd <prepared-repository>
git push -u origin <target-branch>
If the agent cannot expose an interactive prompt to the user, stop at this command and ask the user to run it. Resume with fetch and SHA verification after the user reports success. Never place the PAT in the remote URL, shell command, environment variable, chat, log, or repository file.
Troubleshooting
If GCM reports that secretservice cannot be used without a graphical interface, first confirm where the setting came from:
git config --show-origin --get-all credential.credentialStore
git config --show-origin --get-all credential.helper
Then use the repository-local cache configuration above for this push, or rerun Git inside the real graphical session. Do not disable TLS verification. Install the organization's trusted CA correctly or stop and report the certificate issue.
Official references: GCM installation, credential stores, and GCM configuration.