103 lines
5.4 KiB
Markdown
103 lines
5.4 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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`:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/install.md), [credential stores](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/credstores.md), and [GCM configuration](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md).
|