gh-setup-git-identity 0.7.0 → 0.8.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md CHANGED
@@ -1,5 +1,39 @@
1
1
  # gh-setup-git-identity
2
2
 
3
+ ## 0.8.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 0171f4e: Add `--repair` and `--no-auto-login` CLI options
8
+
9
+ ## New Features
10
+
11
+ ### `--repair` option
12
+
13
+ Repair git identity configuration without triggering the login flow. This is useful when:
14
+
15
+ - Git operations fail with "empty ident name not allowed" error
16
+ - The `user.name` or `user.email` was accidentally cleared or corrupted
17
+ - You want to reconfigure git identity without going through login again
18
+
19
+ The `--repair` option requires existing GitHub CLI authentication.
20
+
21
+ ### `--no-auto-login` option
22
+
23
+ Disable automatic login if not authenticated. Instead of starting the interactive login process, the tool will exit with an error and show manual authentication instructions.
24
+
25
+ This is useful in scripts or automated environments where you want to fail fast rather than wait for an interactive login prompt.
26
+
27
+ ## 0.7.1
28
+
29
+ ### Patch Changes
30
+
31
+ - 469bcb7: Add case study documentation and multi-environment usage warning for GitHub OAuth token limits
32
+
33
+ - Add comprehensive case study for OAuth token invalidation issue (#26)
34
+ - Update README.md with multi-environment usage section documenting the 10-token limit
35
+ - Add CLI warning when OAuth device flow authentication is triggered
36
+
3
37
  ## 0.7.0
4
38
 
5
39
  ### Minor Changes
package/README.md CHANGED
@@ -93,6 +93,8 @@ Git Identity Options:
93
93
  --local, -l Set git config locally (in current repository)
94
94
  --dry-run, --dry Dry run - show what would be done without making changes
95
95
  --verify Verify current git identity configuration
96
+ --repair Repair git identity without triggering login (requires existing auth)
97
+ --no-auto-login Disable automatic login if not authenticated
96
98
  --verbose, -v Enable verbose output
97
99
 
98
100
  GitHub Authentication Options:
@@ -210,6 +212,33 @@ git config --local user.name
210
212
  git config --local user.email
211
213
  ```
212
214
 
215
+ ### Repairing Configuration
216
+
217
+ If your git identity configuration becomes corrupted or misconfigured (e.g., empty `user.name` or `user.email`), you can use the `--repair` option to fix it without triggering a new login:
218
+
219
+ ```bash
220
+ # Repair git identity using existing authentication
221
+ gh-setup-git-identity --repair
222
+ ```
223
+
224
+ This is useful when:
225
+ - Git operations fail with "empty ident name not allowed" error
226
+ - The `user.name` or `user.email` was accidentally cleared or corrupted
227
+ - You want to reconfigure git identity without going through the login flow again
228
+
229
+ The `--repair` option requires that you're already authenticated with GitHub CLI. If not authenticated, it will show helpful instructions for manual authentication.
230
+
231
+ ### Disabling Auto-Login
232
+
233
+ By default, if you're not authenticated, the tool will automatically start the GitHub CLI login process. You can disable this behavior:
234
+
235
+ ```bash
236
+ # Fail immediately if not authenticated (don't auto-login)
237
+ gh-setup-git-identity --no-auto-login
238
+ ```
239
+
240
+ This is useful in scripts or automated environments where you want to fail fast rather than wait for an interactive login prompt.
241
+
213
242
  ## Library Usage
214
243
 
215
244
  ### Basic Example
@@ -317,6 +346,50 @@ Get current git identity configuration.
317
346
 
318
347
  **Returns:** `Promise<{username: string|null, email: string|null}>`
319
348
 
349
+ ## Multi-Environment Usage
350
+
351
+ ### Important: GitHub OAuth Token Limits
352
+
353
+ GitHub limits OAuth tokens to **10 per user/application/scope combination**. If you use `gh-setup-git-identity` on more than 10 machines or environments, the oldest tokens will be automatically revoked by GitHub, causing authentication failures on those machines.
354
+
355
+ For more details, see the [GitHub documentation on token expiration and revocation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation).
356
+
357
+ ### Recommended: Use Personal Access Tokens (PATs)
358
+
359
+ For multi-environment setups (Docker containers, CI/CD, multiple servers), we recommend using Personal Access Tokens instead of the OAuth device flow:
360
+
361
+ 1. Create a PAT at https://github.com/settings/tokens with these scopes:
362
+ - `repo`, `workflow`, `user`, `read:org`, `gist`
363
+
364
+ 2. Authenticate using the token:
365
+
366
+ ```bash
367
+ # Option 1: Via stdin
368
+ echo "ghp_your_token_here" | gh-setup-git-identity --with-token
369
+
370
+ # Option 2: Via environment variable (recommended for automation)
371
+ export GH_TOKEN="ghp_your_token_here"
372
+ gh-setup-git-identity
373
+ ```
374
+
375
+ ### Why PATs Are Better for Multi-Environment
376
+
377
+ - **No token limit**: PATs don't count toward the 10-token OAuth limit
378
+ - **Consistent authentication**: Same token works across all environments
379
+ - **Explicit control**: You manage the token lifecycle
380
+ - **CI/CD friendly**: Easy to inject as a secret
381
+
382
+ ### Revoking Old OAuth Tokens
383
+
384
+ If you've accumulated OAuth tokens and need to clean up:
385
+
386
+ 1. Go to **GitHub Settings** > **Applications** > **Authorized OAuth Apps**
387
+ 2. Find "GitHub CLI" in the list
388
+ 3. Click **Revoke** to remove all OAuth tokens
389
+ 4. Re-authenticate with `gh-setup-git-identity`
390
+
391
+ For a detailed case study of this issue, see [docs/case-studies/issue-26/](./docs/case-studies/issue-26/).
392
+
320
393
  ## Configuration
321
394
 
322
395
  ### Environment Variables
@@ -0,0 +1,229 @@
1
+ # Case Study: GitHub OAuth Token Invalidation and Prevention Strategies (Issue #26)
2
+
3
+ ## Executive Summary
4
+
5
+ This case study investigates the GitHub OAuth token invalidation issue experienced when using `gh-setup-git-identity` across multiple environments. The investigation reveals that this behavior is a documented GitHub security feature, not a bug. When more than 10 OAuth tokens exist for the same user/application/scope combination, GitHub automatically revokes the oldest tokens.
6
+
7
+ This document explores the root causes, reconstructs the timeline of events, and proposes solutions including potential modifications to `gh-setup-git-identity` to mitigate token accumulation.
8
+
9
+ ## Issue Description
10
+
11
+ **Issue URL:** https://github.com/link-foundation/gh-setup-git-identity/issues/26
12
+
13
+ **Related Analysis:** https://github.com/link-assistant/hive-mind/pull/1022 (Issue #1021)
14
+
15
+ **Reported Behavior:**
16
+ > At the same time I was executing `gh-setup-git-identity` command on the remote server. And for some reason executing `gh-setup-git-identity` remotely did destroy GitHub Auth session locally in docker. That is strange.
17
+
18
+ When running `gh-setup-git-identity` on multiple machines, authentication sessions on other machines become invalid. This creates a "musical chairs" effect where the most recent authentication causes the oldest one to fail.
19
+
20
+ ## Root Cause Analysis
21
+
22
+ ### Primary Root Cause: GitHub's OAuth Token Limits
23
+
24
+ From the [official GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation):
25
+
26
+ > "There is a limit of ten tokens that are issued per user/application/scope combination, and a rate limit of ten tokens created per hour. If an application creates more than ten tokens for the same user and the same scopes, the oldest tokens with the same user/application/scope combination are revoked."
27
+
28
+ ### Secondary Cause: gh auth login Token Accumulation
29
+
30
+ When `gh auth login` is executed (which `gh-setup-git-identity` uses internally), it:
31
+
32
+ 1. Creates a new OAuth token through GitHub's device code flow
33
+ 2. Stores the new token in the local credentials store
34
+ 3. **Does NOT revoke the previous token** on GitHub's side
35
+
36
+ From [GitHub CLI Issue #9233](https://github.com/cli/cli/issues/9233):
37
+ > "Whenever an already logged-in user runs a gh auth login or gh auth refresh, a new OAuth app token is generated and replaces the previous token in the credentials store. The problem is that the old token is not revoked during this process."
38
+
39
+ This is currently a known limitation and marked as "blocked" because the GitHub platform doesn't provide an API for the CLI to revoke its own tokens.
40
+
41
+ ### How These Combine to Cause the Issue
42
+
43
+ ```
44
+ Timeline of Token Accumulation:
45
+
46
+ Machine A (Docker) Machine B (Server) Machine C (Local)
47
+ | | |
48
+ v v v
49
+ Token #1 Token #2 Token #3
50
+ | | |
51
+ v v v
52
+ Token #4 Token #5 Token #6
53
+ | | |
54
+ v v v
55
+ Token #7 Token #8 Token #9
56
+ | | |
57
+ | v |
58
+ | Token #10 |
59
+ | | |
60
+ | v |
61
+ | gh-setup-git-identity |
62
+ | (creates Token #11) |
63
+ | | |
64
+ v v v
65
+ Token #1 Token #11 Token #3
66
+ REVOKED! (newest - valid) (still valid)
67
+ | | |
68
+ X | |
69
+ Machine A | |
70
+ auth FAILS! | |
71
+ ```
72
+
73
+ ## Timeline of Events
74
+
75
+ Based on the log file from https://gist.github.com/konard/a430347f7f9aff41b7e0c64a7289712a:
76
+
77
+ | Timestamp (UTC) | Event | Token State |
78
+ |-----------------|-------|-------------|
79
+ | 09:05:36 | `solve` command started in Docker | Token valid |
80
+ | 09:05:42 | GitHub auth check skipped (`--no-tool-check`) | Token valid |
81
+ | 09:05:55 | Git push successful to fork | Token valid |
82
+ | 09:06:02 | PR created successfully | Token valid |
83
+ | ~09:06-09:12 | (Unknown) Remote server runs `gh-setup-git-identity` | **New token created** |
84
+ | 09:12:59 | Git push fails: "Invalid username or token" | **Token revoked** |
85
+ | 09:13:06 | `gh auth status` confirms token invalid | Token invalid |
86
+
87
+ The token was valid at 09:05:55 (successful push) but became invalid by 09:12:59 (approximately 7 minutes later), indicating an external event caused the revocation.
88
+
89
+ ## Evidence from Logs
90
+
91
+ ### Successful Authentication (09:05:55)
92
+ ```
93
+ [2025-12-28T09:05:55.246Z] [INFO] Push exit code: 0
94
+ [2025-12-28T09:05:55.246Z] [INFO] Push output: remote:
95
+ remote: Create a pull request for 'issue-133-434c3df37b90' on GitHub by visiting:
96
+ ```
97
+
98
+ ### Authentication Failure (09:12:59)
99
+ ```
100
+ Exit code 128
101
+ remote: Invalid username or token. Password authentication is not supported for Git operations.
102
+ fatal: Authentication failed for 'https://github.com/konard/andchir-install_scripts.git/'
103
+ ```
104
+
105
+ ### gh auth status Confirmation (09:13:06)
106
+ ```
107
+ github.com
108
+ X Failed to log in to github.com account konard (/home/hive/.config/gh/hosts.yml)
109
+ - Active account: true
110
+ - The token in /home/hive/.config/gh/hosts.yml is invalid.
111
+ - To re-authenticate, run: gh auth login -h github.com
112
+ ```
113
+
114
+ ## Proposed Solutions
115
+
116
+ ### Question from Issue #26
117
+
118
+ > Can we maybe use our `gh-setup-git-identity` tool to actually revoke all 10 tokens?
119
+
120
+ **Answer: Not directly through code modification.**
121
+
122
+ The GitHub CLI itself cannot revoke OAuth tokens programmatically because GitHub's platform doesn't expose an API endpoint for OAuth apps to revoke their own tokens. This is documented in [GitHub CLI Issue #9233](https://github.com/cli/cli/issues/9233).
123
+
124
+ However, there are several alternative approaches:
125
+
126
+ ### Solution 1: Use Personal Access Tokens (PATs) Instead of OAuth Flow
127
+
128
+ **Recommended for multi-environment setups**
129
+
130
+ PATs don't count toward the 10-token OAuth limit and can be shared across environments.
131
+
132
+ ```bash
133
+ # Create a PAT at GitHub Settings > Developer settings > Personal access tokens
134
+ # Then authenticate:
135
+ echo "ghp_your_token_here" | gh-setup-git-identity --with-token
136
+ ```
137
+
138
+ **Pros:**
139
+ - No token accumulation
140
+ - Same token works across all environments
141
+ - Explicit control over token lifecycle
142
+
143
+ **Cons:**
144
+ - Requires manual token creation
145
+ - Token management responsibility shifts to user
146
+
147
+ ### Solution 2: Revoke Tokens Manually via GitHub Settings
148
+
149
+ Users can manually clean up old tokens:
150
+
151
+ 1. Go to **GitHub Settings** > **Applications** > **Authorized OAuth Apps**
152
+ 2. Find "GitHub CLI" entry
153
+ 3. Click "Revoke" to remove old authorizations
154
+ 4. Re-authenticate with `gh-setup-git-identity`
155
+
156
+ ### Solution 3: Use GH_TOKEN/GITHUB_TOKEN Environment Variable
157
+
158
+ For automated/CI environments:
159
+
160
+ ```bash
161
+ export GH_TOKEN="ghp_your_personal_access_token"
162
+ # or
163
+ export GITHUB_TOKEN="ghp_your_personal_access_token"
164
+
165
+ # gh-setup-git-identity will use this token
166
+ gh-setup-git-identity
167
+ ```
168
+
169
+ ### Solution 4: Add Warning Documentation to gh-setup-git-identity
170
+
171
+ Add documentation warning users about the 10-token limit when using multiple environments.
172
+
173
+ ### Solution 5: Implement Token Reuse Check (Code Change)
174
+
175
+ Modify `gh-setup-git-identity` to:
176
+ 1. Check if current token is valid before triggering new authentication
177
+ 2. Skip `gh auth login` if already authenticated (currently implemented but can be enhanced)
178
+ 3. Warn users when they attempt to re-authenticate unnecessarily
179
+
180
+ ### Solution 6: Add Token Revocation Guidance in CLI Output
181
+
182
+ When authentication is triggered, output a message like:
183
+
184
+ ```
185
+ Note: GitHub limits OAuth tokens to 10 per user/application/scope.
186
+ If you use multiple environments, consider using Personal Access Tokens instead.
187
+ To revoke old tokens: https://github.com/settings/applications
188
+ ```
189
+
190
+ ## Recommendations
191
+
192
+ ### For Individual Users
193
+
194
+ 1. **For multi-environment setups**: Use Personal Access Tokens (PATs) instead of OAuth device flow
195
+ 2. **Regularly audit tokens**: Visit GitHub Settings > Applications > Authorized OAuth Apps
196
+ 3. **Share tokens across environments**: Use `GH_TOKEN` environment variable with a single PAT
197
+
198
+ ### For gh-setup-git-identity Development
199
+
200
+ 1. **Add documentation** about GitHub's 10-token limit in README.md
201
+ 2. **Add CLI warning** when triggering authentication about token limits
202
+ 3. **Enhance `--with-token` mode** documentation for multi-environment usage
203
+ 4. **Consider adding `--revoke-first` flag** that prompts users to revoke via GitHub settings before re-authenticating
204
+
205
+ ## Conclusion
206
+
207
+ The token invalidation issue is expected behavior due to GitHub's OAuth token management:
208
+
209
+ 1. **GitHub limits OAuth tokens to 10 per user/application/scope combination**
210
+ 2. **When the limit is exceeded, the oldest tokens are automatically revoked**
211
+ 3. **`gh auth login` creates new tokens without revoking old ones**
212
+ 4. **This is a platform limitation, not a bug in `gh-setup-git-identity`**
213
+
214
+ The recommended mitigation is to use Personal Access Tokens (PATs) for multi-environment setups, which provides better control over token lifecycle and avoids the 10-token OAuth limit.
215
+
216
+ ## References
217
+
218
+ - [GitHub Token Expiration and Revocation Documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation)
219
+ - [GitHub CLI gh auth login Manual](https://cli.github.com/manual/gh_auth_login)
220
+ - [GitHub CLI Issue #9233: Invalidate previous OAuth token](https://github.com/cli/cli/issues/9233)
221
+ - [GitHub CLI Issue #5924: Support for short-lived OAuth tokens](https://github.com/cli/cli/issues/5924)
222
+ - [Original Issue Analysis (hive-mind #1021)](https://github.com/link-assistant/hive-mind/pull/1022)
223
+ - [Original Issue Gist Log](https://gist.github.com/konard/a430347f7f9aff41b7e0c64a7289712a)
224
+
225
+ ## Appendix: Related Files
226
+
227
+ - `timeline.md` - Detailed event timeline reconstruction
228
+ - `solutions.md` - Comprehensive solution comparison matrix
229
+ - `raw-logs/` - Redacted log excerpts for reference
@@ -0,0 +1,69 @@
1
+ # Authentication Failure Log Excerpts
2
+
3
+ Source: https://gist.github.com/konard/a430347f7f9aff41b7e0c64a7289712a
4
+
5
+ **Note**: OAuth tokens have been redacted for security.
6
+
7
+ ## Successful Push (09:05:55)
8
+
9
+ ```log
10
+ [2025-12-28T09:05:54.123Z] [INFO] 📤 Pushing branch: To remote repository...
11
+ [2025-12-28T09:05:54.123Z] [INFO] Push command: git push -u origin issue-133-434c3df37b90
12
+ [2025-12-28T09:05:55.245Z] [INFO] Push exit code: 0
13
+ [2025-12-28T09:05:55.246Z] [INFO] Push output: remote:
14
+ remote: Create a pull request for 'issue-133-434c3df37b90' on GitHub by visiting:
15
+ remote: https://github.com/konard/andchir-install_scripts/pull/new/issue-133-434c3df37b90
16
+ remote:
17
+ To https://github.com/konard/andchir-install_scripts.git
18
+ * [new branch] issue-133-434c3df37b90 -> issue-133-434c3df37b90
19
+ branch 'issue-133-434c3df37b90' set up to track 'origin/issue-133-434c3df37b90'.
20
+ [2025-12-28T09:05:55.247Z] [INFO] ✅ Branch pushed: Successfully to remote
21
+ ```
22
+
23
+ ## First Authentication Failure (09:12:59)
24
+
25
+ ```log
26
+ [2025-12-28T09:12:59.875Z]
27
+ "content": "Exit code 128\nremote: Invalid username or token. Password authentication is not supported for Git operations.\nfatal: Authentication failed for 'https://github.com/konard/andchir-install_scripts.git/'",
28
+ "is_error": true
29
+ ```
30
+
31
+ ## gh auth status Confirmation (09:13:06)
32
+
33
+ ```log
34
+ [2025-12-28T09:13:06.601Z]
35
+ "content": "Exit code 1\ngithub.com\n X Failed to log in to github.com account konard (/home/hive/.config/gh/hosts.yml)\n - Active account: true\n - The token in /home/hive/.config/gh/hosts.yml is invalid.\n - To re-authenticate, run: gh auth login -h github.com\n - To forget about this account, run: gh auth logout -h github.com -u konard",
36
+ "is_error": true
37
+ ```
38
+
39
+ ## Subsequent Retry Failures
40
+
41
+ ### Attempt with git push
42
+ ```log
43
+ "content": "remote: Invalid username or token. Password authentication is not supported for Git operations.\nfatal: Authentication failed for 'https://github.com/konard/andchir-install_scripts.git/'\nPush with gh auth token",
44
+ ```
45
+
46
+ ### Attempt with git credential helper
47
+ ```log
48
+ "content": "Exit code 128\ngit: 'credential-!/usr/bin/gh' is not a git command. See 'git --help'.\nremote: Invalid username or token. Password authentication is not supported for Git operations.\nfatal: Authentication failed for 'https://github.com/konard/andchir-install_scripts.git/'",
49
+ ```
50
+
51
+ ## AI Recognition of Issue
52
+
53
+ ```log
54
+ "text": "The token might be expired or invalid. Let me try using `gh` to push:"
55
+ ```
56
+
57
+ ```log
58
+ "text": "The GitHub CLI token is invalid. I'll need help from the user to authenticate. Let me comment on the PR with my progress and ask for help:"
59
+ ```
60
+
61
+ ## Key Observations
62
+
63
+ 1. **Token was valid at 09:05:55** - Push succeeded
64
+ 2. **Token was invalid by 09:12:59** - ~7 minute gap
65
+ 3. **No token refresh or re-auth occurred** in the Docker container during this time
66
+ 4. **The token file existed** but was marked as invalid by GitHub
67
+ 5. **Multiple retry strategies failed** - The token was revoked server-side, not locally
68
+
69
+ This confirms that an external event (likely `gh-setup-git-identity` running on another machine) caused GitHub to revoke the token during the ~7 minute window.
@@ -0,0 +1,265 @@
1
+ # Solutions for GitHub OAuth Token Accumulation
2
+
3
+ ## Overview
4
+
5
+ This document provides a comprehensive analysis of potential solutions to prevent GitHub OAuth token invalidation when using `gh-setup-git-identity` across multiple environments.
6
+
7
+ ## Solution Comparison Matrix
8
+
9
+ | Solution | Implementation Effort | User Effort | Effectiveness | Breaking Change |
10
+ |----------|----------------------|-------------|---------------|-----------------|
11
+ | Use PATs | None (existing feature) | Medium | High | No |
12
+ | Manual token revocation | None | High | Medium | No |
13
+ | GH_TOKEN env variable | None (existing feature) | Low | High | No |
14
+ | Add documentation | Low | Low | Medium | No |
15
+ | Add CLI warning | Low | None | Medium | No |
16
+ | Token reuse check | Medium | None | Medium | No |
17
+
18
+ ## Detailed Solutions
19
+
20
+ ### Solution 1: Personal Access Tokens (PATs)
21
+
22
+ **Priority: Recommended for multi-environment users**
23
+
24
+ Personal Access Tokens don't count toward the 10-token OAuth limit and provide consistent authentication across all environments.
25
+
26
+ #### Implementation
27
+
28
+ No code changes required. Users should:
29
+
30
+ 1. Create a PAT at https://github.com/settings/tokens
31
+ 2. Select appropriate scopes: `repo`, `workflow`, `user`, `read:org`, `gist`
32
+ 3. Use the token with `gh-setup-git-identity`:
33
+
34
+ ```bash
35
+ # Option 1: Via stdin
36
+ echo "ghp_your_token_here" | gh-setup-git-identity --with-token
37
+
38
+ # Option 2: Via environment variable
39
+ export GH_TOKEN="ghp_your_token_here"
40
+ gh-setup-git-identity
41
+ ```
42
+
43
+ #### Pros
44
+ - Complete solution to the problem
45
+ - Same token works everywhere
46
+ - No code changes needed
47
+ - User controls token lifecycle
48
+
49
+ #### Cons
50
+ - Requires manual token creation
51
+ - Users must securely store the token
52
+ - Token rotation is manual
53
+
54
+ ---
55
+
56
+ ### Solution 2: Manual Token Revocation
57
+
58
+ **Priority: Maintenance task for existing users**
59
+
60
+ Users can manually clean up accumulated OAuth tokens.
61
+
62
+ #### Steps
63
+
64
+ 1. Go to **GitHub Settings** > **Applications** > **Authorized OAuth Apps**
65
+ 2. Find "GitHub CLI" in the list
66
+ 3. Click to view details
67
+ 4. Click **Revoke** to remove the authorization
68
+ 5. Re-authenticate with `gh-setup-git-identity`
69
+
70
+ #### Pros
71
+ - Clears all existing OAuth tokens at once
72
+ - Fresh start for token management
73
+
74
+ #### Cons
75
+ - Requires re-authentication on all machines
76
+ - Manual process
77
+ - Doesn't prevent future accumulation
78
+
79
+ ---
80
+
81
+ ### Solution 3: GH_TOKEN Environment Variable
82
+
83
+ **Priority: Recommended for CI/CD and automated environments**
84
+
85
+ Setting a consistent token via environment variable ensures the same credentials are used everywhere.
86
+
87
+ #### Implementation
88
+
89
+ ```bash
90
+ # Add to ~/.bashrc, ~/.zshrc, or CI secrets
91
+ export GH_TOKEN="ghp_your_personal_access_token"
92
+
93
+ # Or
94
+ export GITHUB_TOKEN="ghp_your_personal_access_token"
95
+ ```
96
+
97
+ The GitHub CLI automatically uses these environment variables for authentication.
98
+
99
+ #### Pros
100
+ - Works with existing `gh-setup-git-identity`
101
+ - No code changes needed
102
+ - Ideal for automation
103
+
104
+ #### Cons
105
+ - Requires secure secret management
106
+ - Must be set on each machine/environment
107
+
108
+ ---
109
+
110
+ ### Solution 4: Add Documentation Warning
111
+
112
+ **Priority: Should implement**
113
+
114
+ Add clear documentation about the 10-token limit in the README.
115
+
116
+ #### Proposed README Addition
117
+
118
+ ```markdown
119
+ ## Multi-Environment Usage Warning
120
+
121
+ GitHub limits OAuth tokens to **10 per user/application/scope combination**.
122
+ If you use `gh-setup-git-identity` on more than 10 machines/environments,
123
+ the oldest tokens will be automatically revoked by GitHub.
124
+
125
+ **For multi-environment setups**, we recommend using Personal Access Tokens (PATs):
126
+
127
+ 1. Create a PAT at https://github.com/settings/tokens with these scopes:
128
+ - `repo`, `workflow`, `user`, `read:org`, `gist`
129
+ 2. Authenticate using the token:
130
+ ```bash
131
+ echo "ghp_your_token" | gh-setup-git-identity --with-token
132
+ ```
133
+
134
+ Or set it via environment variable:
135
+ ```bash
136
+ export GH_TOKEN="ghp_your_token"
137
+ gh-setup-git-identity
138
+ ```
139
+
140
+ See the [GitHub documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation) for more details.
141
+ ```
142
+
143
+ ---
144
+
145
+ ### Solution 5: Add CLI Warning
146
+
147
+ **Priority: Should implement**
148
+
149
+ Display a warning when OAuth device flow authentication is triggered.
150
+
151
+ #### Proposed Implementation
152
+
153
+ In `src/cli.js`, after triggering `runGhAuthLogin()`:
154
+
155
+ ```javascript
156
+ // After successful login
157
+ console.log('');
158
+ console.log('Note: GitHub limits OAuth tokens to 10 per user/application.');
159
+ console.log('For multi-environment setups, consider using Personal Access Tokens.');
160
+ console.log('Learn more: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation');
161
+ ```
162
+
163
+ #### Pros
164
+ - Low implementation effort
165
+ - Immediate user awareness
166
+ - Non-breaking change
167
+
168
+ #### Cons
169
+ - Users might ignore the warning
170
+ - Adds verbosity to output
171
+
172
+ ---
173
+
174
+ ### Solution 6: Enhanced Token Reuse Check
175
+
176
+ **Priority: Optional enhancement**
177
+
178
+ Add more robust checking before triggering new authentication.
179
+
180
+ #### Current Behavior
181
+
182
+ `gh-setup-git-identity` already checks if authenticated via `isGhAuthenticated()`:
183
+
184
+ ```javascript
185
+ // src/cli.js
186
+ const authenticated = await isGhAuthenticated({ verbose: config.verbose });
187
+
188
+ if (!authenticated) {
189
+ // ... triggers gh auth login
190
+ }
191
+ ```
192
+
193
+ #### Proposed Enhancement
194
+
195
+ Add additional check for token validity:
196
+
197
+ ```javascript
198
+ const authenticated = await isGhAuthenticated({ verbose: config.verbose });
199
+
200
+ if (authenticated) {
201
+ // Verify token is actually valid by making a simple API call
202
+ const tokenValid = await verifyTokenValidity();
203
+ if (!tokenValid) {
204
+ console.log('Warning: Your token appears to be invalid or revoked.');
205
+ console.log('This may happen if you have authenticated on multiple machines.');
206
+ console.log('');
207
+ console.log('Options:');
208
+ console.log('1. Continue to re-authenticate (may revoke tokens on other machines)');
209
+ console.log('2. Use a Personal Access Token instead (recommended for multi-environment)');
210
+ // Prompt user for choice or proceed with re-auth
211
+ }
212
+ }
213
+ ```
214
+
215
+ ---
216
+
217
+ ## Question: Can gh-setup-git-identity Revoke All 10 Tokens?
218
+
219
+ From Issue #26:
220
+ > Can we may be use our `gh-setup-git-identity` tool to actually revoke all 10 tokens?
221
+
222
+ ### Answer: No, not programmatically
223
+
224
+ **Technical Reason**: GitHub's OAuth platform doesn't provide an API endpoint for OAuth applications to revoke their own tokens. This is documented in [GitHub CLI Issue #9233](https://github.com/cli/cli/issues/9233).
225
+
226
+ The only ways to revoke tokens are:
227
+ 1. **User action**: Through GitHub Settings > Applications > Authorized OAuth Apps
228
+ 2. **Organization admin action**: Through organization settings
229
+ 3. **Token exposure**: GitHub automatically revokes tokens detected in public repositories
230
+
231
+ ### Alternative: Guidance for Manual Revocation
232
+
233
+ We can add a command or output that guides users to revoke tokens:
234
+
235
+ ```javascript
236
+ // Proposed addition to CLI
237
+ if (config.revokeTokens) {
238
+ console.log('');
239
+ console.log('To revoke existing GitHub CLI tokens:');
240
+ console.log('');
241
+ console.log('1. Open: https://github.com/settings/applications');
242
+ console.log('2. Find "GitHub CLI" in the list');
243
+ console.log('3. Click "Revoke" to remove all OAuth tokens');
244
+ console.log('4. Run gh-setup-git-identity again to create a fresh token');
245
+ console.log('');
246
+ process.exit(0);
247
+ }
248
+ ```
249
+
250
+ This could be triggered with a `--revoke-help` flag.
251
+
252
+ ---
253
+
254
+ ## Implementation Priority
255
+
256
+ 1. **Immediate**: Add documentation warning in README.md
257
+ 2. **Short-term**: Add CLI warning when OAuth flow is triggered
258
+ 3. **Medium-term**: Add `--revoke-help` command to guide users
259
+ 4. **Optional**: Implement enhanced token validity checking
260
+
261
+ ## Conclusion
262
+
263
+ The most effective solution for users is to switch to Personal Access Tokens for multi-environment usage. This completely avoids the OAuth token limit issue and provides better control over authentication.
264
+
265
+ For the `gh-setup-git-identity` tool itself, adding documentation and CLI warnings will help users understand and avoid the issue proactively.
@@ -0,0 +1,119 @@
1
+ # Timeline of Events: GitHub Token Invalidation Incident
2
+
3
+ ## Overview
4
+
5
+ This document reconstructs the timeline of events that led to the GitHub authentication token invalidation during a `solve` operation in a Docker container.
6
+
7
+ ## Source Data
8
+
9
+ - **Log File**: https://gist.github.com/konard/a430347f7f9aff41b7e0c64a7289712a
10
+ - **Date**: December 28, 2025
11
+ - **Environment**: Docker container running `solve` command
12
+ - **User**: konard
13
+
14
+ ## Timeline
15
+
16
+ ### Phase 1: Initialization (09:05:36 - 09:05:42)
17
+
18
+ | Timestamp | Event | Status |
19
+ |-----------|-------|--------|
20
+ | 09:05:36.353Z | `solve` command started | - |
21
+ | 09:05:37.334Z | solve v0.51.18 initialized | - |
22
+ | 09:05:42.403Z | GitHub authentication check **skipped** (`--no-tool-check` enabled) | Token assumed valid |
23
+
24
+ **Note**: The `--no-tool-check` flag prevented early detection of token validity issues.
25
+
26
+ ### Phase 2: Repository Operations (09:05:43 - 09:06:07)
27
+
28
+ | Timestamp | Event | Status |
29
+ |-----------|-------|--------|
30
+ | 09:05:43.764Z | Repository visibility check passed | Token valid |
31
+ | 09:05:49.756Z | Fork verified: `konard/andchir-install_scripts` | Token valid |
32
+ | 09:05:52.206Z | Repository cloned successfully | Token valid |
33
+ | 09:05:54.073Z | Initial commit created with CLAUDE.md | Token valid |
34
+ | 09:05:55.245Z | **Git push successful** to fork | **Token confirmed working** |
35
+ | 09:06:02.929Z | Draft PR #134 created successfully | Token valid |
36
+
37
+ **Key Evidence**: The push at 09:05:55 succeeded, proving the token was valid at that time.
38
+
39
+ ### Phase 3: Claude AI Execution (09:06:14 - 09:12:59)
40
+
41
+ | Timestamp | Event | Status |
42
+ |-----------|-------|--------|
43
+ | 09:06:14.090Z | Claude AI execution started | Token still valid |
44
+ | 09:06:14 - 09:12:59 | AI analyzing and implementing solution | Token unknown |
45
+ | **~09:06 - 09:12** | **[EXTERNAL EVENT]** Remote server likely ran `gh-setup-git-identity` | **New token created remotely** |
46
+
47
+ **Critical Gap**: During this ~7 minute window, an external event caused the token to be revoked.
48
+
49
+ ### Phase 4: Authentication Failure (09:12:59 onwards)
50
+
51
+ | Timestamp | Event | Status |
52
+ |-----------|-------|--------|
53
+ | 09:12:59.875Z | **First authentication failure** - `git push` rejected | Token **REVOKED** |
54
+ | 09:13:06.601Z | `gh auth status` confirms token is invalid | Token invalid |
55
+ | 09:13:XX | Multiple retry attempts fail | Token invalid |
56
+ | 09:XX:XX | AI asks for help via PR comment | Session ended |
57
+
58
+ ### Error Messages
59
+
60
+ **First failure (09:12:59)**:
61
+ ```
62
+ Exit code 128
63
+ remote: Invalid username or token. Password authentication is not supported for Git operations.
64
+ fatal: Authentication failed for 'https://github.com/konard/andchir-install_scripts.git/'
65
+ ```
66
+
67
+ **gh auth status output (09:13:06)**:
68
+ ```
69
+ github.com
70
+ X Failed to log in to github.com account konard (/home/hive/.config/gh/hosts.yml)
71
+ - Active account: true
72
+ - The token in /home/hive/.config/gh/hosts.yml is invalid.
73
+ - To re-authenticate, run: gh auth login -h github.com
74
+ ```
75
+
76
+ ## Analysis
77
+
78
+ ### Token Validity Window
79
+
80
+ ```
81
+ Token VALID Token REVOKED
82
+ |-----------------------------|-------------------->
83
+ | |
84
+ 09:05:55 09:12:59
85
+ (push success) (push failure)
86
+
87
+ Gap: ~7 minutes
88
+ ```
89
+
90
+ ### Root Cause Hypothesis
91
+
92
+ Based on the issue description and GitHub's documented OAuth token limits:
93
+
94
+ 1. User had accumulated multiple OAuth tokens across environments
95
+ 2. During the 7-minute window, `gh-setup-git-identity` was executed on a remote server
96
+ 3. This created a new token, pushing the total over GitHub's 10-token limit
97
+ 4. GitHub automatically revoked the oldest token, which was the one in use by the Docker container
98
+ 5. Subsequent git operations in Docker failed due to the revoked token
99
+
100
+ ### Supporting Evidence
101
+
102
+ From the issue description:
103
+ > "At the same time I was executing `gh-setup-git-identity` command on the remote server. And for some reason executing `gh-setup-git-identity` remotely did destroy GitHub Auth session locally in docker."
104
+
105
+ This confirms the hypothesis that token creation on the remote server triggered the revocation.
106
+
107
+ ## Lessons Learned
108
+
109
+ 1. **Authentication checks should not be skipped**: The `--no-tool-check` flag prevented early detection
110
+ 2. **Token validity can change during long operations**: Long-running processes should periodically verify authentication
111
+ 3. **Multi-environment setups require token management strategy**: Using PATs instead of OAuth device flow prevents this issue
112
+ 4. **GitHub's token limits are strictly enforced**: 10 tokens per user/application/scope is a hard limit
113
+
114
+ ## Recommendations
115
+
116
+ 1. Add token validity checks before critical operations (push, PR creation)
117
+ 2. Consider implementing token refresh or re-authentication logic for long-running processes
118
+ 3. Document the multi-environment token limitation prominently
119
+ 4. Recommend PATs for users with multiple environments
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "gh-setup-git-identity",
3
- "version": "0.7.0",
3
+ "version": "0.8.0",
4
4
  "description": "A tool to setup git identity based on current gh user",
5
5
  "type": "module",
6
6
  "main": "src/index.js",
package/src/cli.js CHANGED
@@ -44,6 +44,16 @@ const config = makeConfig({
44
44
  description: 'Verify current git identity configuration',
45
45
  default: false
46
46
  })
47
+ .option('repair', {
48
+ type: 'boolean',
49
+ description: 'Repair git identity configuration without triggering login (requires existing authentication)',
50
+ default: false
51
+ })
52
+ .option('no-auto-login', {
53
+ type: 'boolean',
54
+ description: 'Disable automatic login if not authenticated (exit with error instead)',
55
+ default: false
56
+ })
47
57
  // gh auth login options
48
58
  .option('hostname', {
49
59
  type: 'string',
@@ -108,6 +118,8 @@ const config = makeConfig({
108
118
  .example('$0 --scopes repo,user,gist', 'Authenticate with custom scopes')
109
119
  .example('$0 --git-protocol ssh', 'Use SSH protocol for git operations')
110
120
  .example('$0 --with-token < token.txt', 'Authenticate using a token file')
121
+ .example('$0 --repair', 'Repair git identity without triggering login')
122
+ .example('$0 --no-auto-login', 'Fail if not authenticated instead of auto-login')
111
123
  .help('h')
112
124
  .alias('h', 'help')
113
125
  .version('0.1.0')
@@ -186,8 +198,46 @@ async function main() {
186
198
  // Check if gh is authenticated
187
199
  const authenticated = await isGhAuthenticated({ verbose: config.verbose });
188
200
 
201
+ // Determine if auto-login should be disabled
202
+ // --repair implies no auto-login (it's meant to fix config without triggering login)
203
+ // --no-auto-login explicitly disables auto-login
204
+ const skipAutoLogin = config.repair || config.noAutoLogin;
205
+
189
206
  if (!authenticated) {
207
+ if (skipAutoLogin) {
208
+ // In repair mode or with --no-auto-login, don't attempt to login
209
+ console.error('GitHub CLI is not authenticated.');
210
+ if (config.repair) {
211
+ console.error('');
212
+ console.error('The --repair option requires existing authentication.');
213
+ console.error('Please authenticate first using one of these methods:');
214
+ } else {
215
+ console.error('');
216
+ console.error('Automatic login is disabled (--no-auto-login).');
217
+ console.error('Please authenticate manually using one of these methods:');
218
+ }
219
+ console.error('');
220
+ console.error(' # Option 1: Interactive web-based login');
221
+ console.error(` gh auth login -h ${config.hostname} -s ${config.scopes} --git-protocol ${config.gitProtocol} --web`);
222
+ console.error('');
223
+ console.error(' # Option 2: Token-based login');
224
+ console.error(' echo "ghp_your_token" | gh auth login --with-token');
225
+ console.error('');
226
+ console.error(' # Option 3: Use GH_TOKEN environment variable');
227
+ console.error(' export GH_TOKEN="ghp_your_token"');
228
+ process.exit(1);
229
+ }
230
+
190
231
  console.log('GitHub CLI is not authenticated. Starting authentication...');
232
+ console.log('');
233
+
234
+ // Show token limit warning for OAuth device flow (not when using --with-token)
235
+ if (!config.withToken) {
236
+ console.log('Note: GitHub limits OAuth tokens to 10 per user/application.');
237
+ console.log(' For multi-environment setups, consider using Personal Access Tokens.');
238
+ console.log(' See: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation');
239
+ console.log('');
240
+ }
191
241
 
192
242
  // Prepare auth options from CLI arguments
193
243
  const authOptions = {
@@ -176,3 +176,20 @@ test('default export contains all functions', async () => {
176
176
  assert.ok(typeof defaultExport.setupGitIdentity === 'function');
177
177
  assert.ok(typeof defaultExport.verifyGitIdentity === 'function');
178
178
  });
179
+
180
+ // Test: CLI --repair and --no-auto-login options are present
181
+ // Note: Full CLI integration tests would require mocking the subprocess
182
+ test('CLI module has --repair and --no-auto-login options', async () => {
183
+ // This test verifies the CLI module syntax is correct and options exist
184
+ const fs = await import('node:fs');
185
+ const cliContent = fs.readFileSync(new URL('../src/cli.js', import.meta.url), 'utf-8');
186
+
187
+ // Verify the new options are defined in the CLI
188
+ assert.ok(cliContent.includes("'repair'"), 'CLI should have --repair option');
189
+ assert.ok(cliContent.includes("'no-auto-login'"), 'CLI should have --no-auto-login option');
190
+
191
+ // Verify the repair/no-auto-login logic is implemented
192
+ assert.ok(cliContent.includes('skipAutoLogin'), 'CLI should have skipAutoLogin logic');
193
+ assert.ok(cliContent.includes('config.repair'), 'CLI should check config.repair');
194
+ assert.ok(cliContent.includes('config.noAutoLogin'), 'CLI should check config.noAutoLogin');
195
+ });