@sentry/junior-github 0.5.0 → 0.6.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 (6) hide show
  1. package/package.json +1 -1
  2. package/skills/github/README.md +15 -0
  3. package/skills/github/SKILL.md +24 -10
  4. package/skills/github/references/api-surface.md +12 -2
  5. package/skills/github/references/common-use-cases.md +34 -8
  6. package/skills/github/references/troubleshooting-workarounds.md +3 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sentry/junior-github",
3
- "version": "0.5.0",
3
+ "version": "0.6.0",
4
4
  "private": false,
5
5
  "publishConfig": {
6
6
  "access": "public"
package/skills/github/README.md CHANGED
@@ -57,6 +57,21 @@ Repeat for `preview` and `development` as needed. After env changes, redeploy so
57
57
 
58
58
  Run as a regular sandbox `bash` command while this skill is active:
59
59
 
60
+ Clone a repository with a shallow checkout by default:
61
+
62
+ ```bash
63
+ gh repo clone owner/repo -- --depth=1
64
+ ```
65
+
66
+ Deepen later only if the task needs more history:
67
+
68
+ ```bash
69
+ git -C repo fetch --depth=50 origin
70
+ git -C repo fetch --unshallow
71
+ ```
72
+
73
+ Issue operations still require scoped credentials:
74
+
60
75
  ```bash
61
76
  jr-rpc issue-credential github.issues.write
62
77
  gh issue create --repo owner/repo --title "Example issue" --body-file /vercel/sandbox/tmp/issue.md
package/skills/github/SKILL.md CHANGED
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: github
3
- description: Manage GitHub issue workflows via GitHub App identity with concise, evidence-backed content. Use when users ask to open, edit, label, comment on, close/reopen, or inspect GitHub issues via /github, especially when command-level CLI guidance is needed.
3
+ description: Manage GitHub issue workflows 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 via /github, or when they need `gh repo clone` guidance, especially shallow-clone defaults and exact CLI commands.
4
4
  requires-capabilities: github.issues.read github.issues.write github.issues.comment github.labels.write
5
5
  uses-config: github.repo
6
6
  allowed-tools: bash
@@ -8,19 +8,30 @@ allowed-tools: bash
8
8
 
9
9
  # GitHub Operations
10
10
 
11
- Use this skill for `/github` workflows in the harness. Issues are the primary supported surface today.
11
+ Use this skill for `/github` workflows in the harness. Issues are the primary surface. Repository checkout is limited to `gh repo clone` guidance and execution when local code context is needed.
12
12
 
13
13
  ## Workflow
14
14
 
15
15
  1. Confirm operation and target:
16
- - Determine `create`, `update`, `comment`, `labels`, `state`, or read-only inspection.
17
- - Resolve repository (`owner/repo`) and issue number for non-create operations.
16
+ - Determine `clone`, `create`, `update`, `comment`, `labels`, `state`, or read-only inspection.
17
+ - Resolve repository (`owner/repo`) and issue number for non-create issue operations.
18
18
  - If repository is not explicit in args, query channel config:
19
19
  - `jr-rpc config get github.repo`
20
20
  - If config exists and is valid `owner/repo`, use it as default.
21
21
  - If repository is still missing, ask the user for `owner/repo`.
22
22
 
23
- 2. Classify issue type before drafting:
23
+ 2. Handle repository checkout first when operation is `clone`:
24
+ - Default to a shallow clone for local inspection or one-off edits:
25
+ - `gh repo clone owner/repo [directory] -- --depth=1`
26
+ - Pass extra `git clone` flags only after `--`.
27
+ - Use a full-history clone only when the task explicitly needs history-heavy operations such as `git blame`, `git bisect`, tag/release archaeology, or broad commit-log analysis.
28
+ - If the initial shallow clone is insufficient, deepen incrementally instead of recloning:
29
+ - `git -C <directory> fetch --depth=<n> origin`
30
+ - `git -C <directory> fetch --unshallow`
31
+ - When cloning a fork, keep the default upstream remote behavior unless the user asks for a different remote name.
32
+ - After checkout, report the local directory and whether the clone is shallow or full. Stop here for clone-only requests.
33
+
34
+ 3. Classify issue type before drafting:
24
35
  - Use explicit user type when provided (`bug`, `feature`, `task`).
25
36
  - Otherwise infer from intent:
26
37
  - `bug`: broken behavior, regression, error, failure.
@@ -28,7 +39,7 @@ Use this skill for `/github` workflows in the harness. Issues are the primary su
28
39
  - `task`: maintenance, cleanup, docs, refactor, operational chore.
29
40
  - Default to `task` when uncertain.
30
41
 
31
- 3. Draft issue content:
42
+ 4. Draft issue content:
32
43
  - Load the type-specific template:
33
44
  - `bug`: [references/issue-template-bug.md](references/issue-template-bug.md)
34
45
  - `feature`: [references/issue-template-feature.md](references/issue-template-feature.md)
@@ -45,28 +56,31 @@ Use this skill for `/github` workflows in the harness. Issues are the primary su
45
56
  - When creating a new issue on behalf of a user, append a final attribution line at the end of the body in the form `Action taken on behalf of <name>.`
46
57
  - Use the clearest available user identifier from conversation context. Prefer a human name, then stable handle, and do not omit attribution for delegated mutations.
47
58
 
48
- 4. Execute operation:
59
+ 5. Execute operation:
49
60
  - Issue credential for the required capability before API calls:
50
61
  - Read-only (`gh issue view`, comment reads via `gh api`): `jr-rpc issue-credential github.issues.read`
51
62
  - Create/update/state changes: `jr-rpc issue-credential github.issues.write`
52
63
  - Comments: `jr-rpc issue-credential github.issues.comment`
53
64
  - Labels: `jr-rpc issue-credential github.labels.write`
65
+ - Repository checkout does not need an issue credential step. Use `gh repo clone` directly.
54
66
  - Resolve command and flags from [references/api-surface.md](references/api-surface.md).
55
67
  - Execute using `gh` CLI directly. Use [references/github-issue-api.md](references/github-issue-api.md) for exact command shapes.
56
68
  - Use [references/common-use-cases.md](references/common-use-cases.md) for ready-to-run operation patterns.
57
69
  - If an operation fails, follow [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) before retrying.
58
70
  - Read [references/sandbox-runtime.md](references/sandbox-runtime.md) for credential delivery details.
59
71
 
60
- 5. Report result:
61
- - Return canonical issue URL, issue number, issue type, applied changes, and confidence.
72
+ 6. Report result:
73
+ - Return canonical issue URL, issue number, issue type, applied changes, and confidence for issue workflows.
74
+ - For clone operations, return the repository, local directory, clone mode (`shallow` or `full`), and any follow-up deepen/unshallow action taken.
62
75
  - Include references used for verified claims.
63
76
 
64
77
  ## Guardrails
65
78
 
66
79
  - Execute operations as soon as required fields are available. Do not pause for confirmation unless the user explicitly asks for preview/dry-run.
67
80
  - Require explicit confirmation only for close/reopen or destructive broad rewrites.
81
+ - Default to shallow clones for efficiency. Do not use a full clone unless the task requires repository history or the user asks for it.
68
82
  - Never claim verification without citing sources.
69
83
  - For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
70
84
  - Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
71
85
  - If repository or installation access is missing, stop and return a concrete remediation message.
72
- - Scope is issue workflows only. Do not execute pull-request or repository admin mutations in this skill.
86
+ - Scope is issue workflows plus repository checkout. Do not execute pull-request or repository admin mutations in this skill.
package/skills/github/references/api-surface.md CHANGED
@@ -1,6 +1,6 @@
1
- # GitHub Issue CLI API Surface
1
+ # GitHub CLI API Surface
2
2
 
3
- This skill supports issue workflows only.
3
+ This skill supports issue workflows plus repository checkout via `gh repo clone`.
4
4
 
5
5
  All operations use `gh` CLI.
6
6
 
@@ -8,6 +8,7 @@ All operations use `gh` CLI.
8
8
 
9
9
  | Capability | Commands |
10
10
  | --- | --- |
11
+ | none required | `gh repo clone` |
11
12
  | `github.issues.read` | `gh issue view`, `gh api /repos/.../comments` |
12
13
  | `github.issues.write` | `gh issue create`, `gh issue edit`, `gh issue close`, `gh issue reopen` |
13
14
  | `github.issues.comment` | `gh issue comment` |
@@ -17,6 +18,9 @@ All operations use `gh` CLI.
17
18
 
18
19
  | Operation | Command |
19
20
  | --- | --- |
21
+ | Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1` |
22
+ | Deepen shallow clone | `git -C DIRECTORY fetch --depth=N origin` |
23
+ | Convert shallow clone to full | `git -C DIRECTORY fetch --unshallow` |
20
24
  | Create issue | `gh issue create --repo owner/repo --title "..." [--body-file PATH]` |
21
25
  | Update issue fields | `gh issue edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]` |
22
26
  | Close issue | `gh issue close NUMBER --repo owner/repo [--comment "..."]` |
@@ -41,6 +45,12 @@ Set repo default:
41
45
  jr-rpc config set github.repo owner/repo
42
46
  ```
43
47
 
48
+ Pass extra `git clone` flags after `--`:
49
+
50
+ ```bash
51
+ gh repo clone owner/repo -- --depth=1 --filter=blob:none
52
+ ```
53
+
44
54
  Issue scoped credentials:
45
55
 
46
56
  ```bash
package/skills/github/references/common-use-cases.md CHANGED
@@ -1,8 +1,34 @@
1
- # Common GitHub Issue CLI Use Cases
1
+ # Common GitHub CLI Use Cases
2
2
 
3
3
  Use these patterns as direct execution playbooks.
4
4
 
5
- ## 1) Create a bug issue
5
+ ## 1) Clone a repository for local work
6
+
7
+ Default to a shallow clone unless the task requires full history:
8
+
9
+ ```bash
10
+ gh repo clone owner/repo -- --depth=1
11
+ ```
12
+
13
+ Clone into a specific directory:
14
+
15
+ ```bash
16
+ gh repo clone owner/repo worktree/repo -- --depth=1
17
+ ```
18
+
19
+ ## 2) Deepen a shallow clone only when needed
20
+
21
+ ```bash
22
+ git -C worktree/repo fetch --depth=50 origin
23
+ ```
24
+
25
+ Convert to a full clone:
26
+
27
+ ```bash
28
+ git -C worktree/repo fetch --unshallow
29
+ ```
30
+
31
+ ## 3) Create a bug issue
6
32
 
7
33
  ```bash
8
34
  jr-rpc issue-credential github.issues.write
@@ -15,14 +41,14 @@ gh issue create --repo owner/repo --title "OAuth token refresh fails in long-run
15
41
  Action taken on behalf of Jane Doe.
16
42
  ```
17
43
 
18
- ## 2) Patch issue title/body
44
+ ## 4) Patch issue title/body
19
45
 
20
46
  ```bash
21
47
  jr-rpc issue-credential github.issues.write
22
48
  gh issue edit 123 --repo owner/repo --title "Clarify retry semantics for lock contention" --body-file /vercel/sandbox/tmp/revised-issue.md
23
49
  ```
24
50
 
25
- ## 3) Close or reopen issue
51
+ ## 5) Close or reopen issue
26
52
 
27
53
  ```bash
28
54
  jr-rpc issue-credential github.issues.write
@@ -35,14 +61,14 @@ Reopen:
35
61
  gh issue reopen 123 --repo owner/repo
36
62
  ```
37
63
 
38
- ## 4) Add implementation comment
64
+ ## 6) Add implementation comment
39
65
 
40
66
  ```bash
41
67
  jr-rpc issue-credential github.issues.comment
42
68
  gh issue comment 123 --repo owner/repo --body-file /vercel/sandbox/tmp/comment.md
43
69
  ```
44
70
 
45
- ## 5) Apply triage labels
71
+ ## 7) Apply triage labels
46
72
 
47
73
  ```bash
48
74
  jr-rpc issue-credential github.labels.write
@@ -55,14 +81,14 @@ Remove labels:
55
81
  gh issue edit 123 --repo owner/repo --remove-label needs-triage
56
82
  ```
57
83
 
58
- ## 6) Read issue details before mutation
84
+ ## 8) Read issue details before mutation
59
85
 
60
86
  ```bash
61
87
  jr-rpc issue-credential github.issues.read
62
88
  gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body
63
89
  ```
64
90
 
65
- ## 7) Read comment history in JSON
91
+ ## 9) Read comment history in JSON
66
92
 
67
93
  ```bash
68
94
  jr-rpc issue-credential github.issues.read
package/skills/github/references/troubleshooting-workarounds.md CHANGED
@@ -1,15 +1,17 @@
1
- # GitHub Issue CLI Troubleshooting
1
+ # GitHub CLI Troubleshooting
2
2
 
3
3
  Use this table to recover quickly while keeping operations deterministic.
4
4
 
5
5
  | Symptom | Likely cause | Fix |
6
6
  | --- | --- | --- |
7
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`. |
8
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. |
9
10
  | `GraphQL: Could not resolve to a Repository` | Repo slug is wrong or inaccessible. | Validate `owner/repo` and confirm app installation on target repository. |
10
11
  | 401 Unauthorized | Credential not issued for current command scope. | Run `jr-rpc issue-credential <capability>` for the exact command and retry once. |
11
12
  | 403 Forbidden | App lacks required permission on repo. | Confirm GitHub App permissions and installation scope. |
12
13
  | 404 Not Found | Issue number or repo is wrong. | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`. |
14
+ | `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. |
13
15
  | `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. |
14
16
  | `gh issue edit` does not change labels | Wrong flag usage or missing label capability context. | Use repeated `--add-label/--remove-label` flags and issue `github.labels.write` credential first. |
15
17
  | Comment command fails with empty body | Body file missing/empty. | Ensure comment file exists and has content before `gh issue comment`. |