@sentry/junior-github 0.24.1 → 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.
Files changed (7) hide show
  1. package/package.json +1 -1
  2. package/skills/github/README.md +7 -9
  3. package/skills/github/SKILL.md +27 -17
  4. package/skills/github/references/api-surface.md +8 -16
  5. package/skills/github/references/common-use-cases.md +1 -12
  6. package/skills/github/references/sandbox-runtime.md +4 -3
  7. package/skills/github/references/troubleshooting-workarounds.md +17 -16
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sentry/junior-github",
3
- "version": "0.24.1",
3
+ "version": "0.25.0",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "access": "public"
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
- - Credentials are issued lazily when `jr-rpc issue-credential <capability>` is run.
65
- - Issued credentials are reused for the rest of the current turn.
66
- - Sandbox does not receive raw tokens via env; host applies scoped Authorization header transforms for GitHub API calls.
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 scoped credentials:
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
- Use `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.
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, but the host runtime still decides when to mint credentials and the agent can request broader GitHub capabilities when the task requires them.
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, and repository checkout via GitHub CLI with concise, evidence-backed content. Use when users ask to open, edit, label, comment on, close/reopen, or inspect GitHub issues, view or create pull requests, or when they need `gh repo clone` guidance, especially shallow-clone defaults and exact CLI commands.
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 both `jr-rpc issue-credential --target ...` and `gh` commands whenever the task targets a specific repository. Do not rely on a stale `github.repo` default when hopping between repos.
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 capability scoping as an operational safety rail that reduces accidental writes and wrong-repo mutations. It is not a perfect command-by-command permission model.
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, first issue `github.contents.write --target owner/repo` and run `git push`.
135
- - For PR creation, then issue `github.pull-requests.write --target owner/repo` and run `gh pr create --repo owner/repo --head BRANCH ...`.
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: it requires `github.contents.write`, not just `github.pull-requests.write`.
138
- - Treat issue comments and label edits as `github.issues.write`.
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
 
package/skills/github/references/api-surface.md CHANGED
@@ -4,9 +4,10 @@ All operations use `gh` CLI. Commands must be deterministic and non-interactive.
4
4
 
5
5
  ## Authentication
6
6
 
7
- Issue credentials with `jr-rpc issue-credential <capability>` before executing commands. The runtime handles token injection transparently.
8
- GitHub capabilities are repo-scoped. Pass `--target owner/repo` to `jr-rpc issue-credential` and `--repo owner/repo` to `gh` unless you intentionally rely on a verified `github.repo` default for the same repository.
9
- Treat capability scope as a safety rail that reduces accidental writes and wrong-repo mutations, not as a perfect command-by-command security boundary.
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
- ## Credential and config helpers
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 with `github.contents.write`, then use `--head` so `gh` does not trigger hidden push/fork behavior.
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`.
package/skills/github/references/common-use-cases.md CHANGED
@@ -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
- Issue credentials first, then default to a shallow clone:
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
  ```
package/skills/github/references/sandbox-runtime.md CHANGED
@@ -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. Issue credentials with `jr-rpc issue-credential <capability>` before executing commands. See [api-surface.md](api-surface.md) for the capability-to-command mapping.
15
- 2. Credentials are scoped per command execution. Do not persist tokens in files.
16
- 3. If 401/403 appears after credential issuance, reissue once, then stop with remediation guidance.
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.
package/skills/github/references/troubleshooting-workarounds.md CHANGED
@@ -2,24 +2,25 @@
2
2
 
3
3
  Use this table to recover quickly while keeping operations deterministic.
4
4
 
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 credential issued without explicit repo scope. | Pass `--target owner/repo` to `jr-rpc issue-credential ...` and `--repo owner/repo` to the `gh` command for the target repository. |
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 | Credential not issued for current command scope. | Run `jr-rpc issue-credential <capability>` for the exact command and retry once. |
13
- | 403 Forbidden | App lacks required permission on repo. | Confirm GitHub App permissions and installation scope. |
14
- | 404 Not Found | Issue number or repo is wrong. | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`. |
15
- | `gh pr create` fails with auth/permission errors or tries to push interactively | `gh pr create` entered its push/fork path, but only PR-write auth was issued. | Issue `github.contents.write --target owner/repo`, push the branch explicitly, then issue `github.pull-requests.write --target owner/repo` and rerun `gh pr create --repo owner/repo --head BRANCH ...`. |
16
- | `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. |
17
- | `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. |
18
- | `gh issue edit` does not change labels | Wrong flag usage or missing issue-write capability context. | Use repeated `--add-label/--remove-label` flags and issue `github.issues.write` credential first. |
19
- | Comment command fails with empty body | Body file missing/empty. | Ensure comment file exists and has content before `gh issue comment`. |
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 reissuing credentials.
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.