@sentry/junior-github 0.21.0 → 0.22.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/README.md +1 -1
- package/package.json +1 -1
- package/plugin.yaml +3 -2
- package/skills/github/README.md +49 -14
- package/skills/github/SKILL.md +56 -10
- package/skills/github/references/api-surface.md +26 -19
- package/skills/github/references/common-use-cases.md +21 -9
- package/skills/github/references/troubleshooting-workarounds.md +15 -13
package/README.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# @sentry/junior-github
|
|
2
2
|
|
|
3
|
-
`@sentry/junior-github` adds GitHub issue workflows to Junior using a GitHub App.
|
|
3
|
+
`@sentry/junior-github` adds GitHub issue, pull request, and repository workflows to Junior using a GitHub App.
|
|
4
4
|
|
|
5
5
|
Install it alongside `@sentry/junior`:
|
|
6
6
|
|
package/package.json
CHANGED
package/plugin.yaml
CHANGED
|
@@ -4,8 +4,6 @@ description: GitHub issue management via GitHub App
|
|
|
4
4
|
capabilities:
|
|
5
5
|
- issues.read
|
|
6
6
|
- issues.write
|
|
7
|
-
- issues.comment
|
|
8
|
-
- labels.write
|
|
9
7
|
- contents.read
|
|
10
8
|
- contents.write
|
|
11
9
|
- pull-requests.read
|
|
@@ -27,6 +25,9 @@ credentials:
|
|
|
27
25
|
target:
|
|
28
26
|
type: repo
|
|
29
27
|
config-key: repo
|
|
28
|
+
command-flags:
|
|
29
|
+
- --repo
|
|
30
|
+
- -R
|
|
30
31
|
|
|
31
32
|
runtime-dependencies:
|
|
32
33
|
- type: system
|
package/skills/github/README.md
CHANGED
|
@@ -5,28 +5,40 @@ This skill uses host-issued GitHub App installation tokens.
|
|
|
5
5
|
## 1) Create/install GitHub App
|
|
6
6
|
|
|
7
7
|
In GitHub:
|
|
8
|
+
|
|
8
9
|
1. Go to `Settings -> Developer settings -> GitHub Apps -> New GitHub App`.
|
|
9
10
|
2. Set app name and callback URL (any valid HTTPS URL is fine if you do not use web flow).
|
|
10
11
|
3. Under repository permissions, grant:
|
|
12
|
+
|
|
11
13
|
- Issues: Read and write
|
|
14
|
+
- Contents: Read and write
|
|
15
|
+
- Pull requests: Read and write
|
|
12
16
|
- Metadata: Read
|
|
17
|
+
|
|
13
18
|
4. Create the app and generate a private key.
|
|
14
19
|
5. Install the app on the target org/repo(s).
|
|
15
20
|
|
|
16
21
|
Install the app on target repos/orgs and collect:
|
|
22
|
+
|
|
17
23
|
- `GITHUB_APP_ID`
|
|
18
24
|
- `GITHUB_APP_PRIVATE_KEY` (PEM)
|
|
19
25
|
|
|
20
26
|
## 2) Configure host runtime
|
|
21
27
|
|
|
22
28
|
Set on the harness host (never in skill files):
|
|
29
|
+
|
|
23
30
|
- `GITHUB_APP_ID`
|
|
24
31
|
- `GITHUB_APP_PRIVATE_KEY`
|
|
25
32
|
- `GITHUB_INSTALLATION_ID`
|
|
26
33
|
|
|
34
|
+
Current limitation: one Junior deployment uses one GitHub App installation ID.
|
|
35
|
+
That works for repositories covered by the same installation, but not for repositories that live
|
|
36
|
+
under different app installations across orgs/accounts.
|
|
37
|
+
|
|
27
38
|
### Vercel env setup (multiline-safe)
|
|
28
39
|
|
|
29
40
|
`GITHUB_APP_PRIVATE_KEY` is accepted as:
|
|
41
|
+
|
|
30
42
|
- Raw PEM (multiline)
|
|
31
43
|
- Escaped-newline PEM (single-line with `\n`)
|
|
32
44
|
- Base64-encoded PEM
|
|
@@ -70,15 +82,34 @@ git -C repo fetch --depth=50 origin
|
|
|
70
82
|
git -C repo fetch --unshallow
|
|
71
83
|
```
|
|
72
84
|
|
|
73
|
-
|
|
85
|
+
GitHub operations still require scoped credentials:
|
|
74
86
|
|
|
75
87
|
```bash
|
|
76
|
-
jr-rpc issue-credential github.issues.write
|
|
88
|
+
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
77
89
|
gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
|
|
78
90
|
```
|
|
79
91
|
|
|
80
92
|
`gh` supports either direct `GITHUB_TOKEN` (for local debugging) or sandbox-level header injection.
|
|
81
|
-
Use `github.issues.read` for read-only commands
|
|
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.
|
|
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.
|
|
96
|
+
|
|
97
|
+
Be careful with mixed-surface PR commands:
|
|
98
|
+
|
|
99
|
+
- `gh pr edit` title/body/base/reviewer changes fit `github.pull-requests.write`.
|
|
100
|
+
- `gh pr edit` label changes fit `github.issues.write`.
|
|
101
|
+
- `gh pr edit` assignee/milestone changes fit `github.issues.write`.
|
|
102
|
+
- `gh pr close --comment` may need `github.issues.write`.
|
|
103
|
+
- `gh pr close --delete-branch` needs `github.contents.write`.
|
|
104
|
+
|
|
105
|
+
For PR creation in automation, push explicitly and use `--head`:
|
|
106
|
+
|
|
107
|
+
```bash
|
|
108
|
+
jr-rpc issue-credential github.contents.write --target owner/repo
|
|
109
|
+
git -C repo push -u origin BRANCH
|
|
110
|
+
jr-rpc issue-credential github.pull-requests.write --target owner/repo
|
|
111
|
+
gh pr create --repo owner/repo --head BRANCH --base main --title "Example PR" --body-file /vercel/sandbox/tmp/pr.md
|
|
112
|
+
```
|
|
82
113
|
|
|
83
114
|
Optional: set a default repository once per channel/thread context so `--repo` is not needed each turn:
|
|
84
115
|
|
|
@@ -91,7 +122,8 @@ jr-rpc config set github.repo getsentry/junior
|
|
|
91
122
|
- `pnpm skills:check`
|
|
92
123
|
- Create issue in a test repo.
|
|
93
124
|
- Update/comment/label the same issue.
|
|
94
|
-
-
|
|
125
|
+
- Push a test branch and create a draft PR with `--head`.
|
|
126
|
+
- Use read-only commands (`gh issue view`, `gh api .../comments`, `gh pr view`) for issue inspection.
|
|
95
127
|
|
|
96
128
|
## 6) Production verification (step-by-step)
|
|
97
129
|
|
|
@@ -104,13 +136,16 @@ jr-rpc config set github.repo getsentry/junior
|
|
|
104
136
|
4. Run `/github` to create an issue in a safe test repo.
|
|
105
137
|
5. Verify the issue is authored by the GitHub App identity.
|
|
106
138
|
6. Run `/github` to update title/body, add/remove labels, and add a comment.
|
|
107
|
-
7.
|
|
108
|
-
8. Verify
|
|
109
|
-
9. Verify
|
|
110
|
-
10.
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
|
|
116
|
-
|
|
139
|
+
7. Push a test branch and run `/github` to create a draft PR using explicit repo targeting and `--head`.
|
|
140
|
+
8. Verify all mutations succeed and are attributed to the app.
|
|
141
|
+
9. Verify GitHub API calls succeed while this skill is active without writing tokens into sandbox env/files.
|
|
142
|
+
10. Verify raw token values are never printed in output or logs.
|
|
143
|
+
11. Check logs for:
|
|
144
|
+
|
|
145
|
+
- `credential_issue_request`
|
|
146
|
+
- `credential_issue_success`
|
|
147
|
+
- `credential_inject_start`
|
|
148
|
+
- `credential_inject_cleanup`
|
|
149
|
+
|
|
150
|
+
12. Verify logs contain no token/private-key values.
|
|
151
|
+
13. Negative test: target a repo without app installation and confirm explicit failure.
|
package/skills/github/SKILL.md
CHANGED
|
@@ -1,47 +1,51 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: github
|
|
3
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.
|
|
4
|
+
requires-capabilities: github.issues.read github.issues.write github.contents.read github.contents.write github.pull-requests.read github.pull-requests.write
|
|
5
5
|
uses-config: github.repo
|
|
6
6
|
allowed-tools: bash
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
# GitHub Operations
|
|
10
10
|
|
|
11
|
-
Issue workflows and repository checkout via `gh` CLI.
|
|
11
|
+
Issue workflows, pull request operations, and repository checkout via `gh` CLI.
|
|
12
12
|
|
|
13
13
|
## Reference loading
|
|
14
14
|
|
|
15
15
|
Load references conditionally based on the operation:
|
|
16
16
|
|
|
17
|
-
| Operation
|
|
18
|
-
|
|
|
19
|
-
| Any operation
|
|
20
|
-
| `clone`
|
|
21
|
-
| `create`, `
|
|
22
|
-
| On failure
|
|
17
|
+
| Operation | Load |
|
|
18
|
+
| ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| Any operation | [references/api-surface.md](references/api-surface.md) |
|
|
20
|
+
| `clone`, `pull request create` | [references/common-use-cases.md](references/common-use-cases.md) |
|
|
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
|
+
| On failure | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
|
|
23
23
|
|
|
24
24
|
## Workflow
|
|
25
25
|
|
|
26
26
|
### 1. Resolve operation and target
|
|
27
27
|
|
|
28
|
-
- Determine whether the task is `clone
|
|
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
29
|
- Resolve repository (`owner/repo`). If it is not explicit, query channel config with `jr-rpc config get github.repo`.
|
|
30
30
|
- If config exists and is valid `owner/repo`, use it as the default.
|
|
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
|
+
- 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.
|
|
33
35
|
|
|
34
36
|
### 2. Execute by operation type
|
|
35
37
|
|
|
36
38
|
**Clone** → Follow the clone path below.
|
|
37
39
|
**Issue operation** → Follow the issue path below.
|
|
40
|
+
**Pull request inspection** → Follow the pull request inspection path below.
|
|
41
|
+
**Pull request mutation** → Follow the pull request mutation path below.
|
|
38
42
|
|
|
39
43
|
---
|
|
40
44
|
|
|
41
45
|
### Clone path
|
|
42
46
|
|
|
43
47
|
- Issue a `contents.read` credential scoped to the target repository before cloning:
|
|
44
|
-
- `jr-rpc issue-credential github.contents.read --
|
|
48
|
+
- `jr-rpc issue-credential github.contents.read --target owner/repo`
|
|
45
49
|
- Default to a shallow clone.
|
|
46
50
|
- Use exact command forms from [references/api-surface.md](references/api-surface.md) or [references/common-use-cases.md](references/common-use-cases.md).
|
|
47
51
|
- Deepen incrementally only when the task needs repository history.
|
|
@@ -85,9 +89,11 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
85
89
|
#### 5. Execute operation
|
|
86
90
|
|
|
87
91
|
- Issue the narrowest matching capability credential before executing.
|
|
92
|
+
- Pass `--target owner/repo` when issuing repo-scoped GitHub credentials.
|
|
88
93
|
- Use fully specified, non-interactive `gh` commands from [references/api-surface.md](references/api-surface.md).
|
|
89
94
|
- Use [references/common-use-cases.md](references/common-use-cases.md) only when you need a concrete command pattern.
|
|
90
95
|
- 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.
|
|
91
97
|
|
|
92
98
|
#### 6. Report result
|
|
93
99
|
|
|
@@ -96,6 +102,46 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
96
102
|
- Keep routine issue-creation steps silent. Do not post progress chatter about duplicate checks, drafting, credential issuance, or command execution before the final result.
|
|
97
103
|
- 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.`
|
|
98
104
|
|
|
105
|
+
---
|
|
106
|
+
|
|
107
|
+
### Pull request inspection path
|
|
108
|
+
|
|
109
|
+
#### 3. Execute inspection
|
|
110
|
+
|
|
111
|
+
- Issue `github.pull-requests.read --target owner/repo` before authenticated read-only PR commands.
|
|
112
|
+
- Use exact read-only `gh pr` commands from [references/api-surface.md](references/api-surface.md).
|
|
113
|
+
- Skip branch resolution and push logic for inspection-only work.
|
|
114
|
+
|
|
115
|
+
#### 4. Report result
|
|
116
|
+
|
|
117
|
+
- Return canonical PR URL, PR number when available, target repository, and the fields the user asked to inspect.
|
|
118
|
+
- If the requested PR cannot be resolved, report the exact not-found or auth failure and stop.
|
|
119
|
+
|
|
120
|
+
---
|
|
121
|
+
|
|
122
|
+
### Pull request mutation path
|
|
123
|
+
|
|
124
|
+
#### 3. Resolve mutation inputs
|
|
125
|
+
|
|
126
|
+
- For PR creation, resolve the base branch. Use the explicit user request when present; otherwise use the repository default branch.
|
|
127
|
+
- For PR creation, resolve the head branch from the current checkout or user request.
|
|
128
|
+
- For PR creation, if the current branch may not exist on the remote yet, push it explicitly before PR creation.
|
|
129
|
+
|
|
130
|
+
#### 4. Execute pull request operation
|
|
131
|
+
|
|
132
|
+
- Issue the narrowest matching capability credential before executing, and pass `--target owner/repo` for repo-scoped work.
|
|
133
|
+
- 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 ...`.
|
|
136
|
+
- 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`.
|
|
139
|
+
|
|
140
|
+
#### 5. Report result
|
|
141
|
+
|
|
142
|
+
- Return canonical PR URL, PR number when available, target repository, and applied changes.
|
|
143
|
+
- If PR creation fails after explicit push + explicit repo scoping, report the exact auth or validation failure and stop.
|
|
144
|
+
|
|
99
145
|
## Guardrails
|
|
100
146
|
|
|
101
147
|
### Execution
|
|
@@ -5,24 +5,24 @@ All operations use `gh` CLI. Commands must be deterministic and non-interactive.
|
|
|
5
5
|
## Authentication
|
|
6
6
|
|
|
7
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.
|
|
8
10
|
|
|
9
11
|
## Capability to command mapping
|
|
10
12
|
|
|
11
|
-
| Capability | Commands
|
|
12
|
-
| ---------------------------- |
|
|
13
|
-
| `github.contents.read` | `gh repo clone`, `git fetch`
|
|
14
|
-
| `github.contents.write` | `git push`, `gh api` (create/update file contents)
|
|
15
|
-
| `github.issues.read` | `gh issue view`, `gh api /repos/.../comments`
|
|
16
|
-
| `github.issues.write` | `gh issue create`, `gh issue edit`, `gh issue close`, `gh issue reopen` |
|
|
17
|
-
| `github.
|
|
18
|
-
| `github.
|
|
19
|
-
| `github.pull-requests.read` | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks` |
|
|
20
|
-
| `github.pull-requests.write` | `gh pr create`, `gh pr edit`, `gh pr merge`, `gh pr close` |
|
|
13
|
+
| Capability | Commands |
|
|
14
|
+
| ---------------------------- | ------------------------------------------------------------------------------------------- |
|
|
15
|
+
| `github.contents.read` | `gh repo clone`, `git fetch` |
|
|
16
|
+
| `github.contents.write` | `git push`, `gh api` (create/update file contents), `gh pr merge` |
|
|
17
|
+
| `github.issues.read` | `gh issue view`, `gh api /repos/.../comments` |
|
|
18
|
+
| `github.issues.write` | `gh issue create`, `gh issue edit`, `gh issue comment`, `gh issue close`, `gh issue reopen` |
|
|
19
|
+
| `github.pull-requests.read` | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks` |
|
|
20
|
+
| `github.pull-requests.write` | `gh pr create --head <branch>` after explicit push, `gh pr edit`, `gh pr close` |
|
|
21
21
|
|
|
22
22
|
## Command matrix
|
|
23
23
|
|
|
24
24
|
| Operation | Command |
|
|
25
|
-
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
25
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- | -------- | ---------- |
|
|
26
26
|
| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1` |
|
|
27
27
|
| Deepen shallow clone | `git -C DIRECTORY fetch --depth=N origin` |
|
|
28
28
|
| Convert shallow clone to full | `git -C DIRECTORY fetch --unshallow` |
|
|
@@ -35,6 +35,11 @@ Issue credentials with `jr-rpc issue-credential <capability>` before executing c
|
|
|
35
35
|
| Add comment | `gh issue comment NUMBER --repo owner/repo --body-file PATH` |
|
|
36
36
|
| Read issue | `gh issue view NUMBER --repo owner/repo --json number,title,state,labels,assignees,author,url,body` |
|
|
37
37
|
| Read comments | `gh api /repos/owner/repo/issues/NUMBER/comments --method GET --header "Accept: application/vnd.github+json"` |
|
|
38
|
+
| Push branch before PR creation | `git -C DIRECTORY push -u origin BRANCH` |
|
|
39
|
+
| Create pull request | `gh pr create --repo owner/repo --head BRANCH --base BASE --title "..." --body-file PATH` |
|
|
40
|
+
| Update pull request | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]` |
|
|
41
|
+
| Close pull request | `gh pr close NUMBER --repo owner/repo` |
|
|
42
|
+
| Merge pull request | `gh pr merge NUMBER --repo owner/repo [--merge | --squash | --rebase]` |
|
|
38
43
|
|
|
39
44
|
## Credential and config helpers
|
|
40
45
|
|
|
@@ -53,14 +58,12 @@ jr-rpc config set github.repo owner/repo
|
|
|
53
58
|
Issue scoped credentials:
|
|
54
59
|
|
|
55
60
|
```bash
|
|
56
|
-
jr-rpc issue-credential github.contents.read --
|
|
57
|
-
jr-rpc issue-credential github.contents.write --
|
|
58
|
-
jr-rpc issue-credential github.issues.read
|
|
59
|
-
jr-rpc issue-credential github.issues.write
|
|
60
|
-
jr-rpc issue-credential github.
|
|
61
|
-
jr-rpc issue-credential github.
|
|
62
|
-
jr-rpc issue-credential github.pull-requests.read
|
|
63
|
-
jr-rpc issue-credential github.pull-requests.write
|
|
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
|
|
64
67
|
```
|
|
65
68
|
|
|
66
69
|
## Behavior notes
|
|
@@ -69,4 +72,8 @@ jr-rpc issue-credential github.pull-requests.write
|
|
|
69
72
|
- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
|
|
70
73
|
- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
|
|
71
74
|
- 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.
|
|
76
|
+
- Keep `--repo owner/repo` explicit on authenticated GitHub commands when working across repositories.
|
|
77
|
+
- `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
|
+
- `gh pr close --comment` may need `github.issues.write`, and `gh pr close --delete-branch` needs `github.contents.write`.
|
|
72
79
|
- Return actionable errors for auth, permission, not-found, and validation failures.
|
|
@@ -7,14 +7,14 @@ Use these patterns as direct execution playbooks.
|
|
|
7
7
|
Issue credentials first, then default to a shallow clone:
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
-
jr-rpc issue-credential github.contents.read --
|
|
10
|
+
jr-rpc issue-credential github.contents.read --target owner/repo
|
|
11
11
|
gh repo clone owner/repo -- --depth=1
|
|
12
12
|
```
|
|
13
13
|
|
|
14
14
|
Clone into a specific directory:
|
|
15
15
|
|
|
16
16
|
```bash
|
|
17
|
-
jr-rpc issue-credential github.contents.read --
|
|
17
|
+
jr-rpc issue-credential github.contents.read --target owner/repo
|
|
18
18
|
gh repo clone owner/repo worktree/repo -- --depth=1
|
|
19
19
|
```
|
|
20
20
|
|
|
@@ -33,7 +33,7 @@ git -C worktree/repo fetch --unshallow
|
|
|
33
33
|
## 3) Create a bug issue
|
|
34
34
|
|
|
35
35
|
```bash
|
|
36
|
-
jr-rpc issue-credential github.issues.write
|
|
36
|
+
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
37
37
|
gh issue create --repo owner/repo --title "OAuth token refresh fails in long-running thread" --body-file /vercel/sandbox/tmp/issue.md
|
|
38
38
|
```
|
|
39
39
|
|
|
@@ -46,14 +46,14 @@ Action taken on behalf of Jane Doe.
|
|
|
46
46
|
## 4) Patch issue title/body
|
|
47
47
|
|
|
48
48
|
```bash
|
|
49
|
-
jr-rpc issue-credential github.issues.write
|
|
49
|
+
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
50
50
|
gh issue edit 123 --repo owner/repo --title "Clarify retry semantics for lock contention" --body-file /vercel/sandbox/tmp/revised-issue.md
|
|
51
51
|
```
|
|
52
52
|
|
|
53
53
|
## 5) Close or reopen issue
|
|
54
54
|
|
|
55
55
|
```bash
|
|
56
|
-
jr-rpc issue-credential github.issues.write
|
|
56
|
+
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
57
57
|
gh issue close 123 --repo owner/repo --comment "Fixed in #456"
|
|
58
58
|
```
|
|
59
59
|
|
|
@@ -66,14 +66,14 @@ gh issue reopen 123 --repo owner/repo
|
|
|
66
66
|
## 6) Add implementation comment
|
|
67
67
|
|
|
68
68
|
```bash
|
|
69
|
-
jr-rpc issue-credential github.issues.
|
|
69
|
+
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
70
70
|
gh issue comment 123 --repo owner/repo --body-file /vercel/sandbox/tmp/comment.md
|
|
71
71
|
```
|
|
72
72
|
|
|
73
73
|
## 7) Apply triage labels
|
|
74
74
|
|
|
75
75
|
```bash
|
|
76
|
-
jr-rpc issue-credential github.
|
|
76
|
+
jr-rpc issue-credential github.issues.write --target owner/repo
|
|
77
77
|
gh issue edit 123 --repo owner/repo --add-label bug --add-label needs-triage
|
|
78
78
|
```
|
|
79
79
|
|
|
@@ -86,13 +86,25 @@ gh issue edit 123 --repo owner/repo --remove-label needs-triage
|
|
|
86
86
|
## 8) Read issue details before mutation
|
|
87
87
|
|
|
88
88
|
```bash
|
|
89
|
-
jr-rpc issue-credential github.issues.read
|
|
89
|
+
jr-rpc issue-credential github.issues.read --target owner/repo
|
|
90
90
|
gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body
|
|
91
91
|
```
|
|
92
92
|
|
|
93
93
|
## 9) Read comment history in JSON
|
|
94
94
|
|
|
95
95
|
```bash
|
|
96
|
-
jr-rpc issue-credential github.issues.read
|
|
96
|
+
jr-rpc issue-credential github.issues.read --target owner/repo
|
|
97
97
|
gh api /repos/owner/repo/issues/123/comments --method GET --header "Accept: application/vnd.github+json"
|
|
98
98
|
```
|
|
99
|
+
|
|
100
|
+
## 10) Create a pull request safely in automation
|
|
101
|
+
|
|
102
|
+
Push the branch explicitly before creating the PR. This avoids `gh pr create`
|
|
103
|
+
trying to push or fork implicitly.
|
|
104
|
+
|
|
105
|
+
```bash
|
|
106
|
+
jr-rpc issue-credential github.contents.write --target owner/repo
|
|
107
|
+
git -C worktree/repo push -u origin BRANCH
|
|
108
|
+
jr-rpc issue-credential github.pull-requests.write --target owner/repo
|
|
109
|
+
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
|
+
```
|
|
@@ -2,19 +2,21 @@
|
|
|
2
2
|
|
|
3
3
|
Use this table to recover quickly while keeping operations deterministic.
|
|
4
4
|
|
|
5
|
-
| Symptom
|
|
6
|
-
|
|
|
7
|
-
| `unknown command "issue"` from `gh`
|
|
8
|
-
| `unknown flag: --depth` from `gh repo clone`
|
|
9
|
-
| `Missing required option --repo`
|
|
10
|
-
|
|
|
11
|
-
|
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
| `
|
|
16
|
-
| `
|
|
17
|
-
|
|
|
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`. |
|
|
18
20
|
|
|
19
21
|
## Retry guidance
|
|
20
22
|
|