# Linux GCM Setup

Use this reference when Git runs on Linux, including a remote Linux desktop controlled from Windows. Read [credential persistence](credential-persistence.md) before authentication or configuration changes.

## Inspect and install

Verify Git and GCM with their version commands and identify the effective helper, site account, path policy, and credential store. Reuse a working GCM installation. Linux GCM requires an explicitly selected store. If GCM or required components are missing, use an official verified installation method for the distribution, consistent with task authorization. Do not place administrator passwords in chat or use an unverified download.

A visible remote desktop does not guarantee that a background agent has its D-Bus session or an unlocked keyring. Check availability in the exact session where Git runs.

## Persistent stores

Prefer an existing unlocked Secret Service collection when it is accessible to that session. On a headless host, prefer GCM's `gpg` store backed by `gpg` and `pass` when the graphical keyring is unavailable. Install missing components and guide initialization when the task authorizes it. Do not use GCM plaintext or Git `store` for new credentials.

Before initializing `pass`, inspect the existing password-store directory, its `.gpg-id`, available secret keys, and any configured store path. Reuse a suitable existing setup. Do not run `pass init` over an existing store without understanding its recipients. If no suitable key or store exists, have the user create a GPG key through a trusted local interaction, confirm the full fingerprint, and initialize the intended new password store with `pass init <confirmed-full-fingerprint>`. Do not place a key passphrase in commands, environment variables, logs, or chat. Existing keyring or GPG-agent unlock policies may require the user to unlock the key again.

When authorized, configure `credential.<https-site>.credentialStore` as `secretservice` or `gpg` for the target site, and set the site helper/account/path policy only as needed. Preserve unrelated site settings and existing records. Verify secure readback and a subsequent session; a correctly initialized store alone does not prove that an agent can unlock it unattended.

GCM's `cache` store is memory-only and expires by default after 900 seconds. It can be an explicitly requested temporary fallback, but is not long-term persistence and must not be represented as cross-day reuse.

## Authentication and errors

Try a matching stored credential first. For PATs, use the read-only probe in the credential reference before any potentially failing Git operation that could erase a credential. When a prompt is genuinely necessary, use the user's local GCM interaction; never ask the user to send a token or passphrase in chat. If no secure store can be set up or unlocked, explain the remaining local action instead of silently choosing plaintext or a short cache.

A web SSO/OIDC session does not by itself authorize Git. Use generic OAuth only after checking actual client/server compatibility and refresh behavior; otherwise use a PAT. Keep TLS verification enabled.

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 [configuration](https://github.com/git-ecosystem/git-credential-manager/blob/main/docs/configuration.md).