@sentry/junior-github 0.24.0 → 0.25.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/package.json +1 -1
- package/skills/github/README.md +7 -9
- package/skills/github/SKILL.md +27 -17
- package/skills/github/references/api-surface.md +8 -16
- package/skills/github/references/common-use-cases.md +1 -12
- package/skills/github/references/sandbox-runtime.md +4 -3
- package/skills/github/references/troubleshooting-workarounds.md +17 -16
package/package.json
CHANGED
package/skills/github/README.md
CHANGED
|
@@ -61,9 +61,9 @@ Repeat for `preview` and `development` as needed. After env changes, redeploy so
|
|
|
61
61
|
|
|
62
62
|
## 3) Runtime behavior
|
|
63
63
|
|
|
64
|
-
-
|
|
65
|
-
- Issued credentials are reused
|
|
66
|
-
- Sandbox does not receive raw tokens via env; host applies
|
|
64
|
+
- When the GitHub skill is active, authenticated `gh` and `git` commands cause the runtime to inject GitHub credentials automatically for the current turn.
|
|
65
|
+
- Issued credentials are reused only within the current turn.
|
|
66
|
+
- Sandbox does not receive raw tokens via env; host applies Authorization header transforms for GitHub API calls.
|
|
67
67
|
|
|
68
68
|
## 4) CLI usage
|
|
69
69
|
|
|
@@ -82,17 +82,17 @@ git -C repo fetch --depth=50 origin
|
|
|
82
82
|
git -C repo fetch --unshallow
|
|
83
83
|
```
|
|
84
84
|
|
|
85
|
-
GitHub operations still require
|
|
85
|
+
GitHub operations still require the GitHub skill, but the runtime injects
|
|
86
|
+
credentials automatically when the skill is active:
|
|
86
87
|
|
|
87
88
|
```bash
|
|
88
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
89
89
|
gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
|
|
90
90
|
```
|
|
91
91
|
|
|
92
92
|
`gh` supports either direct `GITHUB_TOKEN` (for local debugging) or sandbox-level header injection.
|
|
93
|
-
|
|
93
|
+
The runtime uses `github.issues.read` for read-only issue commands, `github.issues.write` for issue edits, comments, and labels, `github.contents.write` for pushes and merge operations, and `github.pull-requests.write` for PR mutations after the branch is already on the remote.
|
|
94
94
|
|
|
95
|
-
GitHub capability scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations,
|
|
95
|
+
GitHub capability scoping is a safety rail, not a hard sandbox boundary. It helps prevent accidental write scope and wrong-repo mutations, and the host runtime still decides when to mint credentials. Credential injection is skill-scoped: load the active GitHub skill first, keep repo context explicit, and let the runtime choose the required capability for the command.
|
|
96
96
|
|
|
97
97
|
Be careful with mixed-surface PR commands:
|
|
98
98
|
|
|
@@ -105,9 +105,7 @@ Be careful with mixed-surface PR commands:
|
|
|
105
105
|
For PR creation in automation, push explicitly and use `--head`:
|
|
106
106
|
|
|
107
107
|
```bash
|
|
108
|
-
jr-rpc issue-credential github.contents.write --target owner/repo
|
|
109
108
|
git -C repo push -u origin BRANCH
|
|
110
|
-
jr-rpc issue-credential github.pull-requests.write --target owner/repo
|
|
111
109
|
gh pr create --repo owner/repo --head BRANCH --base main --title "Example PR" --body-file /vercel/sandbox/tmp/pr.md
|
|
112
110
|
```
|
|
113
111
|
|
package/skills/github/SKILL.md
CHANGED
|
@@ -1,7 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: github
|
|
3
|
-
description: Manage GitHub issue workflows, pull request operations,
|
|
4
|
-
requires-capabilities: github.issues.read github.issues.write github.contents.read github.contents.write github.pull-requests.read github.pull-requests.write
|
|
3
|
+
description: Manage GitHub issue workflows, source-code investigation, pull request operations, repository checkout, and implicit GitHub credentials via GitHub CLI with concise, evidence-backed content. Use when users ask to inspect implementation details in a repository, clone code, edit files, answer source-code questions from repo evidence, open/edit/view pull requests, or open/edit/inspect GitHub issues. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
|
|
5
4
|
uses-config: github.repo
|
|
6
5
|
allowed-tools: bash
|
|
7
6
|
---
|
|
@@ -18,6 +17,7 @@ Load references conditionally based on the operation:
|
|
|
18
17
|
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
18
|
| Any operation | [references/api-surface.md](references/api-surface.md) |
|
|
20
19
|
| `clone`, `pull request create` | [references/common-use-cases.md](references/common-use-cases.md) |
|
|
20
|
+
| `source-code investigation` | [references/research-rules.md](references/research-rules.md) |
|
|
21
21
|
| `issue create`, `issue body rewrite` | [references/issue-examples.md](references/issue-examples.md), the matching type-specific template and type-specific rules, and [references/research-rules.md](references/research-rules.md) |
|
|
22
22
|
| On failure | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
|
|
23
23
|
|
|
@@ -25,17 +25,18 @@ Load references conditionally based on the operation:
|
|
|
25
25
|
|
|
26
26
|
### 1. Resolve operation and target
|
|
27
27
|
|
|
28
|
-
- Determine whether the task is `clone`, an issue operation (`create`, `update`, `comment`, `labels`, `state`, or read-only inspection), a pull request inspection (`view`, `list`, `diff`, or `checks`), or a pull request mutation (`create`, `update`, `close`, or `merge`).
|
|
29
|
-
- Resolve repository (`owner/repo`). If it is not explicit, query channel config with `jr-rpc config get github.repo
|
|
30
|
-
- If config exists and is valid `owner/repo`, use it as the default.
|
|
28
|
+
- Determine whether the task is `clone`, `source-code investigation`, an issue operation (`create`, `update`, `comment`, `labels`, `state`, or read-only inspection), a pull request inspection (`view`, `list`, `diff`, or `checks`), or a pull request mutation (`create`, `update`, `close`, or `merge`).
|
|
29
|
+
- Resolve repository (`owner/repo`). If it is not explicit, query channel config with `jr-rpc config get github.repo` before running any `gh` or `git` command.
|
|
30
|
+
- If config exists and is valid `owner/repo`, use it as the default and still pass it explicitly on subsequent `gh` commands instead of relying on ambient CLI context.
|
|
31
31
|
- If repository is still missing, ask the user for `owner/repo`.
|
|
32
32
|
- Resolve the issue number for non-create issue operations.
|
|
33
33
|
- Resolve the pull request number for pull request operations that target an existing PR.
|
|
34
|
-
- Keep `owner/repo` explicit on
|
|
34
|
+
- Keep `owner/repo` explicit on `gh` commands whenever the task targets a specific repository. This keeps the command pointed at the right repo and avoids accidental cross-repo mutations. Do not rely on a stale `github.repo` default when hopping between repos.
|
|
35
35
|
|
|
36
36
|
### 2. Execute by operation type
|
|
37
37
|
|
|
38
38
|
**Clone** → Follow the clone path below.
|
|
39
|
+
**Source-code investigation** → Follow the source-code path below.
|
|
39
40
|
**Issue operation** → Follow the issue path below.
|
|
40
41
|
**Pull request inspection** → Follow the pull request inspection path below.
|
|
41
42
|
**Pull request mutation** → Follow the pull request mutation path below.
|
|
@@ -44,8 +45,6 @@ Load references conditionally based on the operation:
|
|
|
44
45
|
|
|
45
46
|
### Clone path
|
|
46
47
|
|
|
47
|
-
- Issue a `contents.read` credential scoped to the target repository before cloning:
|
|
48
|
-
- `jr-rpc issue-credential github.contents.read --target owner/repo`
|
|
49
48
|
- Default to a shallow clone.
|
|
50
49
|
- Use exact command forms from [references/api-surface.md](references/api-surface.md) or [references/common-use-cases.md](references/common-use-cases.md).
|
|
51
50
|
- Deepen incrementally only when the task needs repository history.
|
|
@@ -54,6 +53,18 @@ Load references conditionally based on the operation:
|
|
|
54
53
|
|
|
55
54
|
---
|
|
56
55
|
|
|
56
|
+
### Source-code investigation path
|
|
57
|
+
|
|
58
|
+
- Use this path for questions like "where is this implemented?", "how does this workflow work in code?", "is there already logic for X?", or "verify this from the repo."
|
|
59
|
+
- Resolve repository (`owner/repo`). If the current workspace already contains the target repository, inspect local files directly before cloning anything.
|
|
60
|
+
- If you need repository access outside the current workspace, keep `owner/repo` explicit on the authenticated command so the command itself targets the correct repository.
|
|
61
|
+
- Default to a shallow clone when you need a fresh checkout; deepen only if the question truly needs history.
|
|
62
|
+
- Prefer the narrowest deterministic evidence that answers the question: local file search, exact file reads, targeted clone inspection, existing issues/PRs, and tests.
|
|
63
|
+
- Cite repository evidence in the reply: file paths, symbols, issue/PR numbers, or commit references when known.
|
|
64
|
+
- If the available evidence is incomplete, say what is unknown instead of guessing.
|
|
65
|
+
|
|
66
|
+
---
|
|
67
|
+
|
|
57
68
|
### Issue path
|
|
58
69
|
|
|
59
70
|
#### 3. Classify issue type
|
|
@@ -88,18 +99,17 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
88
99
|
|
|
89
100
|
#### 5. Execute operation
|
|
90
101
|
|
|
91
|
-
- Issue the narrowest matching capability credential before executing.
|
|
92
|
-
- Pass `--target owner/repo` when issuing repo-scoped GitHub credentials.
|
|
93
102
|
- Use fully specified, non-interactive `gh` commands from [references/api-surface.md](references/api-surface.md).
|
|
94
103
|
- Use [references/common-use-cases.md](references/common-use-cases.md) only when you need a concrete command pattern.
|
|
95
104
|
- Check duplicates silently before creating a new issue. Only mention duplicates when relevant matches are actually found.
|
|
96
|
-
- Treat GitHub
|
|
105
|
+
- Treat GitHub auth as plugin-owned and turn-scoped. The skill determines whether GitHub credentials are available for the turn; explicit repo flags are still for command correctness and mutation safety.
|
|
97
106
|
|
|
98
107
|
#### 6. Report result
|
|
99
108
|
|
|
100
109
|
- Return canonical issue URL, issue number, issue type, applied changes, and confidence.
|
|
101
110
|
- Include references used for verified claims.
|
|
102
111
|
- Keep routine issue-creation steps silent. Do not post progress chatter about duplicate checks, drafting, credential issuance, or command execution before the final result.
|
|
112
|
+
- Never mention silent duplicate checking in the final reply unless you actually found a relevant duplicate that changed the outcome.
|
|
103
113
|
- If duplicate checking found no relevant matches, omit that fact entirely and report only the created issue, for example `Created issue #123: ...`, not `No duplicates found. Creating the issue now.`
|
|
104
114
|
|
|
105
115
|
---
|
|
@@ -108,7 +118,6 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
108
118
|
|
|
109
119
|
#### 3. Execute inspection
|
|
110
120
|
|
|
111
|
-
- Issue `github.pull-requests.read --target owner/repo` before authenticated read-only PR commands.
|
|
112
121
|
- Use exact read-only `gh pr` commands from [references/api-surface.md](references/api-surface.md).
|
|
113
122
|
- Skip branch resolution and push logic for inspection-only work.
|
|
114
123
|
|
|
@@ -129,13 +138,13 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
129
138
|
|
|
130
139
|
#### 4. Execute pull request operation
|
|
131
140
|
|
|
132
|
-
- Issue the narrowest matching capability credential before executing, and pass `--target owner/repo` for repo-scoped work.
|
|
133
141
|
- For PR creation, do not rely on `gh pr create` to push or fork implicitly.
|
|
134
|
-
- For PR creation, if the head branch is not already on the remote,
|
|
135
|
-
-
|
|
142
|
+
- For PR creation, if the head branch is not already on the remote, run `git push` first. That push step needs GitHub write access for the remote repository.
|
|
143
|
+
- If `git push` returns 401, 403, or another auth/permission error, verify the command is still targeting the right repository and retry once. If the error still clearly indicates bad or revoked credentials, rerun the real GitHub command and let the runtime trigger a reconnect flow.
|
|
144
|
+
- After the branch exists remotely, run `gh pr create --repo owner/repo --head BRANCH ...`.
|
|
136
145
|
- For PR creation, use `--head` so `gh` skips its hidden push/fork flow.
|
|
137
|
-
- Treat `gh pr merge` as a contents mutation
|
|
138
|
-
- Treat issue comments and label edits as
|
|
146
|
+
- Treat `gh pr merge` as a contents mutation and keep repository context explicit so the command cannot hit the wrong repository.
|
|
147
|
+
- Treat issue comments and label edits as issue mutations and keep repository context explicit on the command.
|
|
139
148
|
|
|
140
149
|
#### 5. Report result
|
|
141
150
|
|
|
@@ -153,6 +162,7 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
153
162
|
### Quality
|
|
154
163
|
|
|
155
164
|
- Never claim verification without citing sources.
|
|
165
|
+
- Answer source-code and implementation questions from repository evidence, not product framing or generic memory.
|
|
156
166
|
- For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
|
|
157
167
|
- If no relevant duplicates are found, continue directly to draft and create the issue, then report the created issue.
|
|
158
168
|
|
|
@@ -4,9 +4,10 @@ All operations use `gh` CLI. Commands must be deterministic and non-interactive.
|
|
|
4
4
|
|
|
5
5
|
## Authentication
|
|
6
6
|
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
7
|
+
Load the GitHub skill first, then keep `--repo owner/repo` explicit on authenticated `gh` commands unless you intentionally rely on a verified `github.repo` default for the same repository.
|
|
8
|
+
When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc config get github.repo`, then pass the resolved repo explicitly on the actual `gh` command.
|
|
9
|
+
The runtime injects GitHub credentials implicitly for the current turn once the GitHub skill is active.
|
|
10
|
+
Treat explicit repo flags as command-targeting safety rails that reduce accidental writes and wrong-repo mutations, not as a credential-scoping mechanism.
|
|
10
11
|
|
|
11
12
|
## Capability to command mapping
|
|
12
13
|
|
|
@@ -41,7 +42,7 @@ Treat capability scope as a safety rail that reduces accidental writes and wrong
|
|
|
41
42
|
| Close pull request | `gh pr close NUMBER --repo owner/repo` |
|
|
42
43
|
| Merge pull request | `gh pr merge NUMBER --repo owner/repo [--merge | --squash | --rebase]` |
|
|
43
44
|
|
|
44
|
-
##
|
|
45
|
+
## Config helpers
|
|
45
46
|
|
|
46
47
|
Resolve repo default:
|
|
47
48
|
|
|
@@ -55,24 +56,15 @@ Set repo default:
|
|
|
55
56
|
jr-rpc config set github.repo owner/repo
|
|
56
57
|
```
|
|
57
58
|
|
|
58
|
-
Issue scoped credentials:
|
|
59
|
-
|
|
60
|
-
```bash
|
|
61
|
-
jr-rpc issue-credential github.contents.read --target owner/repo
|
|
62
|
-
jr-rpc issue-credential github.contents.write --target owner/repo
|
|
63
|
-
jr-rpc issue-credential github.issues.read --target owner/repo
|
|
64
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
65
|
-
jr-rpc issue-credential github.pull-requests.read --target owner/repo
|
|
66
|
-
jr-rpc issue-credential github.pull-requests.write --target owner/repo
|
|
67
|
-
```
|
|
68
|
-
|
|
69
59
|
## Behavior notes
|
|
70
60
|
|
|
71
61
|
- Prefer `--json` output for machine-readable parsing where available.
|
|
72
62
|
- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
|
|
73
63
|
- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
|
|
74
64
|
- For automation, always fully specify `gh issue create` with `--title` and `--body` or `--body-file`; never rely on interactive prompts.
|
|
75
|
-
- Before `gh pr create`, push the head branch explicitly
|
|
65
|
+
- Before `gh pr create`, push the head branch explicitly, then use `--head` so `gh` does not trigger hidden push/fork behavior.
|
|
66
|
+
- That explicit `git push` step requires GitHub write access to the remote repository.
|
|
67
|
+
- If that explicit `git push` fails with 401/403 or another auth/permission error, verify the repo context and retry the same push once after clearing stale GitHub auth only when the error explicitly indicates bad credentials.
|
|
76
68
|
- Keep `--repo owner/repo` explicit on authenticated GitHub commands when working across repositories.
|
|
77
69
|
- `gh pr edit` is not a single-permission command: title/body/base/reviewer changes fit `github.pull-requests.write`, label, assignee, and milestone changes fit `github.issues.write`, and project flags are outside the current GitHub App capability model.
|
|
78
70
|
- `gh pr close --comment` may need `github.issues.write`, and `gh pr close --delete-branch` needs `github.contents.write`.
|
|
@@ -4,17 +4,15 @@ Use these patterns as direct execution playbooks.
|
|
|
4
4
|
|
|
5
5
|
## 1) Clone a repository for local work
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Default to a shallow clone:
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
jr-rpc issue-credential github.contents.read --target owner/repo
|
|
11
10
|
gh repo clone owner/repo -- --depth=1
|
|
12
11
|
```
|
|
13
12
|
|
|
14
13
|
Clone into a specific directory:
|
|
15
14
|
|
|
16
15
|
```bash
|
|
17
|
-
jr-rpc issue-credential github.contents.read --target owner/repo
|
|
18
16
|
gh repo clone owner/repo worktree/repo -- --depth=1
|
|
19
17
|
```
|
|
20
18
|
|
|
@@ -33,7 +31,6 @@ git -C worktree/repo fetch --unshallow
|
|
|
33
31
|
## 3) Create a bug issue
|
|
34
32
|
|
|
35
33
|
```bash
|
|
36
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
37
34
|
gh issue create --repo owner/repo --title "OAuth token refresh fails in long-running thread" --body-file /vercel/sandbox/tmp/issue.md
|
|
38
35
|
```
|
|
39
36
|
|
|
@@ -46,14 +43,12 @@ Action taken on behalf of Jane Doe.
|
|
|
46
43
|
## 4) Patch issue title/body
|
|
47
44
|
|
|
48
45
|
```bash
|
|
49
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
50
46
|
gh issue edit 123 --repo owner/repo --title "Clarify retry semantics for lock contention" --body-file /vercel/sandbox/tmp/revised-issue.md
|
|
51
47
|
```
|
|
52
48
|
|
|
53
49
|
## 5) Close or reopen issue
|
|
54
50
|
|
|
55
51
|
```bash
|
|
56
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
57
52
|
gh issue close 123 --repo owner/repo --comment "Fixed in #456"
|
|
58
53
|
```
|
|
59
54
|
|
|
@@ -66,14 +61,12 @@ gh issue reopen 123 --repo owner/repo
|
|
|
66
61
|
## 6) Add implementation comment
|
|
67
62
|
|
|
68
63
|
```bash
|
|
69
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
70
64
|
gh issue comment 123 --repo owner/repo --body-file /vercel/sandbox/tmp/comment.md
|
|
71
65
|
```
|
|
72
66
|
|
|
73
67
|
## 7) Apply triage labels
|
|
74
68
|
|
|
75
69
|
```bash
|
|
76
|
-
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
77
70
|
gh issue edit 123 --repo owner/repo --add-label bug --add-label needs-triage
|
|
78
71
|
```
|
|
79
72
|
|
|
@@ -86,14 +79,12 @@ gh issue edit 123 --repo owner/repo --remove-label needs-triage
|
|
|
86
79
|
## 8) Read issue details before mutation
|
|
87
80
|
|
|
88
81
|
```bash
|
|
89
|
-
jr-rpc issue-credential github.issues.read --target owner/repo
|
|
90
82
|
gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body
|
|
91
83
|
```
|
|
92
84
|
|
|
93
85
|
## 9) Read comment history in JSON
|
|
94
86
|
|
|
95
87
|
```bash
|
|
96
|
-
jr-rpc issue-credential github.issues.read --target owner/repo
|
|
97
88
|
gh api /repos/owner/repo/issues/123/comments --method GET --header "Accept: application/vnd.github+json"
|
|
98
89
|
```
|
|
99
90
|
|
|
@@ -103,8 +94,6 @@ Push the branch explicitly before creating the PR. This avoids `gh pr create`
|
|
|
103
94
|
trying to push or fork implicitly.
|
|
104
95
|
|
|
105
96
|
```bash
|
|
106
|
-
jr-rpc issue-credential github.contents.write --target owner/repo
|
|
107
97
|
git -C worktree/repo push -u origin BRANCH
|
|
108
|
-
jr-rpc issue-credential github.pull-requests.write --target owner/repo
|
|
109
98
|
gh pr create --repo owner/repo --head BRANCH --base main --title "fix(repo): narrow GitHub repo scoping" --body-file /vercel/sandbox/tmp/pr.md
|
|
110
99
|
```
|
|
@@ -11,6 +11,7 @@ This skill runs in the harness sandbox (`node22`) and commands execute via the `
|
|
|
11
11
|
|
|
12
12
|
## Credential strategy
|
|
13
13
|
|
|
14
|
-
1.
|
|
15
|
-
2.
|
|
16
|
-
3.
|
|
14
|
+
1. After the GitHub skill is loaded, the runtime injects GitHub credentials implicitly for the current turn.
|
|
15
|
+
2. Keep repository context explicit on `gh` and `git` commands so the command itself targets the correct repo.
|
|
16
|
+
3. Credentials are valid only for the current turn. Do not persist tokens in files.
|
|
17
|
+
4. If auth fails, verify the command still targets the correct repo, then retry the real GitHub command once so the runtime can reconnect automatically when needed.
|
|
@@ -2,24 +2,25 @@
|
|
|
2
2
|
|
|
3
3
|
Use this table to recover quickly while keeping operations deterministic.
|
|
4
4
|
|
|
5
|
-
| Symptom | Likely cause
|
|
6
|
-
| ------------------------------------------------------------------------------- |
|
|
7
|
-
| `unknown command "issue"` from `gh` | CLI version too old or wrong binary.
|
|
8
|
-
| `unknown flag: --depth` from `gh repo clone` | `git clone` flags were passed before `--`.
|
|
9
|
-
| `Missing required option --repo` | Repo not passed and no default was resolved.
|
|
10
|
-
| GitHub command affects or authenticates against the wrong repo | Stale `github.repo` default or
|
|
11
|
-
| `GraphQL: Could not resolve to a Repository` | Repo slug is wrong or inaccessible.
|
|
12
|
-
| 401 Unauthorized |
|
|
13
|
-
| 403
|
|
14
|
-
|
|
|
15
|
-
|
|
|
16
|
-
| `
|
|
17
|
-
| `
|
|
18
|
-
| `
|
|
19
|
-
|
|
|
5
|
+
| Symptom | Likely cause | Fix |
|
|
6
|
+
| ------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
7
|
+
| `unknown command "issue"` from `gh` | CLI version too old or wrong binary. | Verify `gh --version`; ensure GitHub CLI from `gh-cli` repo is installed. |
|
|
8
|
+
| `unknown flag: --depth` from `gh repo clone` | `git clone` flags were passed before `--`. | Pass clone flags after `--`, for example `gh repo clone owner/repo -- --depth=1`. |
|
|
9
|
+
| `Missing required option --repo` | Repo not passed and no default was resolved. | Resolve with `jr-rpc config get github.repo`; pass `--repo owner/repo` explicitly when missing. |
|
|
10
|
+
| GitHub command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` to the `gh` command for the target repository, or update `github.repo` before retrying. |
|
|
11
|
+
| `GraphQL: Could not resolve to a Repository` | Repo slug is wrong or inaccessible. | Validate `owner/repo` and confirm app installation on target repository. |
|
|
12
|
+
| 401 Unauthorized | Repo context is missing, stale, or the stored GitHub auth needs reconnect. | Verify `--repo owner/repo` or `github.repo`, then retry the real command once so the runtime can reconnect automatically when needed. |
|
|
13
|
+
| `git push` fails with 401/403 or auth/permission output | Write auth was stale or the command is targeting the wrong repo. | Verify the remote and repo context, retry the same push once, then confirm app permissions and installation scope if the retry still fails. |
|
|
14
|
+
| 403 Forbidden | App lacks required permission on repo or install scope is too narrow. | Verify the repo context, then confirm GitHub App permissions and installation scope. |
|
|
15
|
+
| 404 Not Found | Issue number or repo is wrong. | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`. |
|
|
16
|
+
| `gh pr create` fails with auth/permission errors or tries to push interactively | The branch was not pushed first, or repo context is wrong. | Push the branch explicitly first, then rerun `gh pr create --repo owner/repo --head BRANCH ...`. |
|
|
17
|
+
| `git blame`, long log history, or old commits are missing after clone | Repo was cloned shallow by design. | Deepen incrementally with `git -C DIRECTORY fetch --depth=N origin`, or use `git -C DIRECTORY fetch --unshallow` when full history is required. |
|
|
18
|
+
| `sandbox setup failed (dnf install gh failed ...)` | `gh` package not available in default repos. | Configure/install from GitHub RPM repo (`gh-cli`) in sandbox dependency bootstrap, then retry. |
|
|
19
|
+
| `gh issue edit` does not change labels | Wrong flag usage or wrong repo context. | Use repeated `--add-label/--remove-label` flags and keep `--repo owner/repo` explicit. |
|
|
20
|
+
| Comment command fails with empty body | Body file missing/empty. | Ensure comment file exists and has content before `gh issue comment`. |
|
|
20
21
|
|
|
21
22
|
## Retry guidance
|
|
22
23
|
|
|
23
|
-
- Retry once for transient auth/transport failures after
|
|
24
|
+
- Retry once for transient auth/transport failures after verifying repo context.
|
|
24
25
|
- Do not loop retries on repeated 401/403/404 validation errors.
|
|
25
26
|
- For persistent permission problems, return explicit remediation and stop.
|