Skip to content

Commit a9d1fae

Browse files
brabojclaude
braboj
and
claude
authored
docs: add credentials recipe (#192)
* 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) <noreply@anthropic.com> * 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) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 72c9028 commit a9d1fae

2 files changed

Lines changed: 154 additions & 0 deletions

File tree

‎chapters/07-playbook.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ For definitions, see [Glossary](09-glossary.md).
4040
| [Remote Management](playbook/remote-management.md) | Add, rename, remove remotes, switch URL, SSH setup |
4141
| [SSH Setup](playbook/ssh-setup.md) | Key generation, agent, GitHub registration, troubleshooting |
4242
| [Bare Repositories](playbook/bare-repositories.md) | Create, clone, convert, and use bare repos as local remotes |
43+
| [Credentials](playbook/credentials.md) | Credential helpers (cache, store, GCM), HTTPS tokens, security |
4344

4445
## Project Structure
4546

‎chapters/recipes/credentials.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
title: "Credentials"
3+
description: "Git recipes for storing and managing credentials — credential helpers (cache, store, manager), HTTPS tokens, SSH keys, and security considerations."
4+
section: "playbook/credentials"
5+
order: 94
6+
---
7+
8+
## Credentials
9+
10+
Every time you push to or pull from a remote over HTTPS, Git needs to
11+
authenticate you. By default, it asks for your username and password
12+
(or token) on every operation. Credential helpers let you store these
13+
credentials so you do not have to type them each time.
14+
15+
For SSH-based authentication, see [SSH Setup](../ssh-setup/).
16+
17+
### HTTPS vs SSH
18+
19+
| Aspect | HTTPS | SSH |
20+
|---|---|---|
21+
| Setup | Simple — works immediately | Requires key generation and registration |
22+
| Authentication | Username + token (or password) | Private key on your machine |
23+
| Credential storage | Via credential helpers (below) | SSH agent holds the key in memory |
24+
| Firewall-friendly | Yes — uses port 443 | May be blocked on port 22 |
25+
26+
HTTPS is easier to start with. SSH avoids credential prompts entirely
27+
once configured. Most developers use SSH for repositories they work
28+
with regularly, and HTTPS for quick one-off clones.
29+
30+
### Credential helpers
31+
32+
A credential helper is a program that stores your credentials so Git
33+
can retrieve them automatically. Git ships with two built-in helpers
34+
and supports external ones.
35+
36+
#### cache
37+
38+
Stores credentials in memory for a limited time (default: 15 minutes).
39+
Nothing is written to disk.
40+
41+
```text
42+
$ git config --global credential.helper cache
43+
44+
# extend to 1 hour (3600 seconds)
45+
$ git config --global credential.helper 'cache --timeout=3600'
46+
```
47+
48+
Best for: shared machines where you do not want credentials on disk.
49+
50+
#### store
51+
52+
Saves credentials in a plaintext file (`~/.git-credentials`). They
53+
persist across reboots but are **not encrypted** — anyone with access
54+
to your home directory can read them.
55+
56+
```text
57+
$ git config --global credential.helper store
58+
```
59+
60+
After the next successful authentication, Git writes the credentials:
61+
62+
```text
63+
$ cat ~/.git-credentials
64+
https://username:ghp_abc123token@github.com
65+
```
66+
67+
Best for: personal machines where convenience matters more than
68+
maximum security. Acceptable when the machine has full-disk encryption.
69+
70+
#### Git Credential Manager
71+
72+
[Git Credential Manager](https://github.com/git-ecosystem/git-credential-manager)
73+
(GCM) is an external helper that stores credentials in your operating
74+
system's secure storage — Windows Credential Manager, macOS Keychain,
75+
or Linux Secret Service.
76+
77+
```text
78+
$ git config --global credential.helper manager
79+
```
80+
81+
The exact value may differ by platform — older installations may use
82+
`manager-core` instead of `manager`.
83+
84+
GCM is included with Git for Windows by default. On macOS and Linux,
85+
install it separately. It supports multi-factor authentication and
86+
OAuth flows for GitHub, GitLab, Bitbucket, and Azure DevOps.
87+
88+
Best for: most developers — encrypted storage, cross-platform, handles
89+
modern authentication flows.
90+
91+
### Check your current helper
92+
93+
```text
94+
$ git config --global credential.helper
95+
manager
96+
```
97+
98+
If this returns nothing, no helper is configured and Git will prompt
99+
every time.
100+
101+
### HTTPS personal access tokens
102+
103+
GitHub and many GitLab instances no longer accept account passwords
104+
for HTTPS Git operations. You need a **personal access token** (PAT)
105+
instead.
106+
107+
To create one on GitHub:
108+
109+
1. Go to **Settings > Developer settings > Personal access tokens > Tokens (classic)**
110+
2. Click **Generate new token**
111+
3. Select scopes — `repo` is enough for push/pull
112+
4. Copy the token — you will not see it again
113+
114+
Use the token as your password when Git prompts:
115+
116+
```text
117+
$ git push origin main
118+
Username: your-username
119+
Password: ghp_abc123... ← paste the token here
120+
```
121+
122+
If you have a credential helper configured, Git stores the token
123+
after the first successful use.
124+
125+
### Security considerations
126+
127+
| Helper | Storage | Risk |
128+
|--------|---------|------|
129+
| cache | Memory only, expires | Low — gone after timeout or reboot |
130+
| store | Plaintext file on disk | High — readable by anyone with file access |
131+
| manager (GCM) | OS encrypted keychain | Low — protected by OS-level security |
132+
133+
Recommendations:
134+
135+
- **Never commit credentials** to a repository — not in code, not in
136+
config files, not in `.env` files that are tracked
137+
- **Prefer GCM or SSH** over the plaintext `store` helper
138+
- **Rotate tokens regularly** — treat them like passwords
139+
- **Use the minimum scope** when creating tokens — `repo` is enough
140+
for most workflows
141+
- **Revoke tokens immediately** if a machine is lost or compromised
142+
143+
### Gotchas
144+
145+
- **`store` keeps credentials in plaintext.** If you switch from
146+
`store` to `manager`, delete `~/.git-credentials` to remove the
147+
old plaintext file.
148+
- **Credential helpers are per-protocol.** An HTTPS helper does not
149+
affect SSH authentication, and vice versa.
150+
- **Multiple helpers can conflict.** If Git behaves unexpectedly,
151+
check for stacked helpers: `git config --global --get-all credential.helper`.
152+
- **Tokens expire.** If pushes suddenly fail with 401 errors, your
153+
token may have expired — generate a new one.

0 commit comments

Comments
 (0)