From a4dccc5f17e920d47edb1ca7034562fa5a78cb22 Mon Sep 17 00:00:00 2001 From: Branimir Georgiev Date: Sun, 26 Apr 2026 12:43:35 +0300 Subject: [PATCH 1/2] docs: add credentials recipe to playbook Covers credential helpers (cache, store, GCM), HTTPS personal access tokens, SSH vs HTTPS comparison, security considerations, and gotchas. Added to playbook index under Remote section. Closes #169 Co-Authored-By: Claude Opus 4.6 (1M context) --- chapters/07-playbook.md | 1 + chapters/recipes/credentials.md | 150 ++++++++++++++++++++++++++++++++ 2 files changed, 151 insertions(+) create mode 100644 chapters/recipes/credentials.md diff --git a/chapters/07-playbook.md b/chapters/07-playbook.md index cfaa6b5..b85bad1 100644 --- a/chapters/07-playbook.md +++ b/chapters/07-playbook.md @@ -40,6 +40,7 @@ For definitions, see [Glossary](09-glossary.md). | [Remote Management](playbook/remote-management.md) | Add, rename, remove remotes, switch URL, SSH setup | | [SSH Setup](playbook/ssh-setup.md) | Key generation, agent, GitHub registration, troubleshooting | | [Bare Repositories](playbook/bare-repositories.md) | Create, clone, convert, and use bare repos as local remotes | +| [Credentials](playbook/credentials.md) | Credential helpers (cache, store, GCM), HTTPS tokens, security | ## Project Structure diff --git a/chapters/recipes/credentials.md b/chapters/recipes/credentials.md new file mode 100644 index 0000000..43b9848 --- /dev/null +++ b/chapters/recipes/credentials.md @@ -0,0 +1,150 @@ +--- +title: "Credentials" +description: "Git recipes for storing and managing credentials — credential helpers (cache, store, manager), HTTPS tokens, SSH keys, and security considerations." +section: "playbook/credentials" +order: 94 +--- + +## Credentials + +Every time you push to or pull from a remote over HTTPS, Git needs to +authenticate you. By default, it asks for your username and password +(or token) on every operation. Credential helpers let you store these +credentials so you do not have to type them each time. + +For SSH-based authentication, see [SSH Setup](../ssh-setup/). + +### HTTPS vs SSH + +| | HTTPS | SSH | +|---|---|---| +| Setup | Simple — works immediately | Requires key generation and registration | +| Authentication | Username + token (or password) | Private key on your machine | +| Credential storage | Via credential helpers (below) | SSH agent holds the key in memory | +| Firewall-friendly | Yes — uses port 443 | May be blocked on port 22 | + +HTTPS is easier to start with. SSH avoids credential prompts entirely +once configured. Most developers use SSH for repositories they work +with regularly, and HTTPS for quick one-off clones. + +### Credential helpers + +A credential helper is a program that stores your credentials so Git +can retrieve them automatically. Git ships with two built-in helpers +and supports external ones. + +#### cache + +Stores credentials in memory for a limited time (default: 15 minutes). +Nothing is written to disk. + +```text +$ git config --global credential.helper cache + +# extend to 1 hour (3600 seconds) +$ git config --global credential.helper 'cache --timeout=3600' +``` + +Best for: shared machines where you do not want credentials on disk. + +#### store + +Saves credentials in a plaintext file (`~/.git-credentials`). They +persist across reboots but are **not encrypted** — anyone with access +to your home directory can read them. + +```text +$ git config --global credential.helper store +``` + +After the next successful authentication, Git writes the credentials: + +```text +$ cat ~/.git-credentials +https://username:ghp_abc123token@github.com +``` + +Best for: personal machines where convenience matters more than +maximum security. Acceptable when the machine has full-disk encryption. + +#### Git Credential Manager + +[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager) +(GCM) is an external helper that stores credentials in your operating +system's secure storage — Windows Credential Manager, macOS Keychain, +or Linux Secret Service. + +```text +$ git config --global credential.helper manager +``` + +GCM is included with Git for Windows by default. On macOS and Linux, +install it separately. It supports multi-factor authentication and +OAuth flows for GitHub, GitLab, Bitbucket, and Azure DevOps. + +Best for: most developers — encrypted storage, cross-platform, handles +modern authentication flows. + +### Check your current helper + +```text +$ git config --global credential.helper +manager +``` + +If this returns nothing, no helper is configured and Git will prompt +every time. + +### HTTPS personal access tokens + +GitHub, GitLab, and Bitbucket no longer accept account passwords for +HTTPS Git operations. You need a **personal access token** (PAT) +instead. + +To create one on GitHub: + +1. Go to **Settings > Developer settings > Personal access tokens > Tokens (classic)** +2. Click **Generate new token** +3. Select scopes — `repo` is enough for push/pull +4. Copy the token — you will not see it again + +Use the token as your password when Git prompts: + +```text +$ git push origin main +Username: your-username +Password: ghp_abc123... ← paste the token here +``` + +If you have a credential helper configured, Git stores the token +after the first successful use. + +### Security considerations + +| Helper | Storage | Risk | +|--------|---------|------| +| cache | Memory only, expires | Low — gone after timeout or reboot | +| store | Plaintext file on disk | High — readable by anyone with file access | +| manager (GCM) | OS encrypted keychain | Low — protected by OS-level security | + +Recommendations: + +- **Never commit credentials** to a repository — not in code, not in + config files, not in `.env` files that are tracked +- **Prefer GCM or SSH** over the plaintext `store` helper +- **Rotate tokens regularly** — treat them like passwords +- **Use the minimum scope** when creating tokens — `repo` is enough + for most workflows +- **Revoke tokens immediately** if a machine is lost or compromised + +### Gotchas + +- **`store` keeps credentials in plaintext.** If you switch from + `store` to `manager`, delete `~/.git-credentials` to remove the + old plaintext file. +- **Credential helpers are per-protocol.** An HTTPS helper does not + affect SSH authentication, and vice versa. +- **Multiple helpers can conflict.** If Git behaves unexpectedly, + check for stacked helpers: `git config --global --get-all credential.helper`. +- **Tokens expire.** If pushes suddenly fail with 401 errors, your + token may have expired — generate a new one. From 72c64b79d5e4936ff06373ad41e50ea8ef5dadbe Mon Sep 17 00:00:00 2001 From: Branimir Georgiev Date: Sun, 26 Apr 2026 12:46:28 +0300 Subject: [PATCH 2/2] docs: fix table header, soften password claim, add platform note Add "Aspect" label to comparison table, note that self-hosted GitLab may still accept passwords, add note about manager-core vs manager. Co-Authored-By: Claude Opus 4.6 (1M context) --- chapters/recipes/credentials.md | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/chapters/recipes/credentials.md b/chapters/recipes/credentials.md index 43b9848..b116a76 100644 --- a/chapters/recipes/credentials.md +++ b/chapters/recipes/credentials.md @@ -16,7 +16,7 @@ For SSH-based authentication, see [SSH Setup](../ssh-setup/). ### HTTPS vs SSH -| | HTTPS | SSH | +| Aspect | HTTPS | SSH | |---|---|---| | Setup | Simple — works immediately | Requires key generation and registration | | Authentication | Username + token (or password) | Private key on your machine | @@ -78,6 +78,9 @@ or Linux Secret Service. $ git config --global credential.helper manager ``` +The exact value may differ by platform — older installations may use +`manager-core` instead of `manager`. + GCM is included with Git for Windows by default. On macOS and Linux, install it separately. It supports multi-factor authentication and OAuth flows for GitHub, GitLab, Bitbucket, and Azure DevOps. @@ -97,8 +100,8 @@ every time. ### HTTPS personal access tokens -GitHub, GitLab, and Bitbucket no longer accept account passwords for -HTTPS Git operations. You need a **personal access token** (PAT) +GitHub and many GitLab instances no longer accept account passwords +for HTTPS Git operations. You need a **personal access token** (PAT) instead. To create one on GitHub: