@sentry/junior-github 0.7.0 → 0.9.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/plugin.yaml +4 -0
- package/skills/github/SKILL.md +81 -56
- package/skills/github/references/api-surface.md +42 -31
- package/skills/github/references/common-use-cases.md +3 -1
- package/skills/github/references/sandbox-runtime.md +3 -25
- package/skills/github/references/github-issue-api.md +0 -54
package/package.json
CHANGED
package/plugin.yaml
CHANGED
package/skills/github/SKILL.md
CHANGED
|
@@ -1,37 +1,59 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: github
|
|
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
|
|
4
|
-
requires-capabilities: github.issues.read github.issues.write github.issues.comment github.labels.write
|
|
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.issues.comment github.labels.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
|
-
|
|
11
|
+
Issue workflows and repository checkout via `gh` CLI.
|
|
12
|
+
|
|
13
|
+
## Reference loading
|
|
14
|
+
|
|
15
|
+
Load references conditionally based on the operation:
|
|
16
|
+
|
|
17
|
+
| Operation | Load |
|
|
18
|
+
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| Any operation | [references/api-surface.md](references/api-surface.md) |
|
|
20
|
+
| `clone` | [references/common-use-cases.md](references/common-use-cases.md) |
|
|
21
|
+
| `create`, `update` | [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) |
|
|
12
23
|
|
|
13
24
|
## Workflow
|
|
14
25
|
|
|
15
|
-
1.
|
|
16
|
-
|
|
17
|
-
-
|
|
18
|
-
-
|
|
19
|
-
|
|
20
|
-
- If config exists and is valid `owner/repo`, use it as default.
|
|
26
|
+
### 1. Resolve operation and target
|
|
27
|
+
|
|
28
|
+
- Determine whether the task is `clone` or an issue operation (`create`, `update`, `comment`, `labels`, `state`, or read-only inspection).
|
|
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.
|
|
21
31
|
- If repository is still missing, ask the user for `owner/repo`.
|
|
32
|
+
- Resolve the issue number for non-create issue operations.
|
|
33
|
+
|
|
34
|
+
### 2. Execute by operation type
|
|
35
|
+
|
|
36
|
+
**Clone** → Follow the clone path below.
|
|
37
|
+
**Issue operation** → Follow the issue path below.
|
|
38
|
+
|
|
39
|
+
---
|
|
40
|
+
|
|
41
|
+
### Clone path
|
|
42
|
+
|
|
43
|
+
- Issue a `contents.read` credential scoped to the target repository before cloning:
|
|
44
|
+
- `jr-rpc issue-credential github.contents.read --repo owner/repo`
|
|
45
|
+
- Default to a shallow clone.
|
|
46
|
+
- 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
|
+
- Deepen incrementally only when the task needs repository history.
|
|
48
|
+
- After cloning, check for `AGENTS.md` in the repo root (and `.github/AGENTS.md`) before making edits. Treat discovered instructions as hard constraints.
|
|
49
|
+
- Report the local directory and whether the clone is shallow or full.
|
|
50
|
+
|
|
51
|
+
---
|
|
52
|
+
|
|
53
|
+
### Issue path
|
|
54
|
+
|
|
55
|
+
#### 3. Classify issue type
|
|
22
56
|
|
|
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:
|
|
35
57
|
- Use explicit user type when provided (`bug`, `feature`, `task`).
|
|
36
58
|
- Otherwise infer from intent:
|
|
37
59
|
- `bug`: broken behavior, regression, error, failure.
|
|
@@ -39,48 +61,51 @@ Use this skill for `/github` workflows in the harness. Issues are the primary su
|
|
|
39
61
|
- `task`: maintenance, cleanup, docs, refactor, operational chore.
|
|
40
62
|
- Default to `task` when uncertain.
|
|
41
63
|
|
|
42
|
-
4. Draft issue content
|
|
43
|
-
|
|
44
|
-
|
|
45
|
-
|
|
46
|
-
|
|
47
|
-
|
|
48
|
-
|
|
49
|
-
|
|
50
|
-
|
|
64
|
+
#### 4. Draft issue content
|
|
65
|
+
|
|
66
|
+
Load the type-specific template and rules:
|
|
67
|
+
|
|
68
|
+
| Type | Template | Research rules |
|
|
69
|
+
| --------- | ---------------------------------------------------------------------------- | -------------------------------------------------------------------- |
|
|
70
|
+
| `bug` | [references/issue-template-bug.md](references/issue-template-bug.md) | [references/issue-type-bug.md](references/issue-type-bug.md) |
|
|
71
|
+
| `feature` | [references/issue-template-feature.md](references/issue-template-feature.md) | [references/issue-type-feature.md](references/issue-type-feature.md) |
|
|
72
|
+
| `task` | [references/issue-template-task.md](references/issue-template-task.md) | [references/issue-type-task.md](references/issue-type-task.md) |
|
|
73
|
+
|
|
74
|
+
Follow [references/research-rules.md](references/research-rules.md) for cross-type research standards.
|
|
75
|
+
|
|
51
76
|
- Generalize conversation context: replace user names, slash-command invocations, channel references, and session-specific fragments with the underlying technical problem.
|
|
52
|
-
-
|
|
53
|
-
-
|
|
54
|
-
|
|
55
|
-
|
|
56
|
-
|
|
57
|
-
-
|
|
58
|
-
|
|
59
|
-
|
|
60
|
-
-
|
|
61
|
-
|
|
62
|
-
|
|
63
|
-
|
|
64
|
-
|
|
65
|
-
- Repository checkout does not need an issue credential step. Use `gh repo clone` directly.
|
|
66
|
-
- Resolve command and flags from [references/api-surface.md](references/api-surface.md).
|
|
67
|
-
- Execute using `gh` CLI directly. Use [references/github-issue-api.md](references/github-issue-api.md) for exact command shapes.
|
|
68
|
-
- Use [references/common-use-cases.md](references/common-use-cases.md) for ready-to-run operation patterns.
|
|
69
|
-
- If an operation fails, follow [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) before retrying.
|
|
70
|
-
- Read [references/sandbox-runtime.md](references/sandbox-runtime.md) for credential delivery details.
|
|
71
|
-
|
|
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.
|
|
77
|
+
- Use [references/issue-examples.md](references/issue-examples.md) to calibrate structure and depth.
|
|
78
|
+
- Include code snippets, related issues, and related PRs only when they materially improve the issue.
|
|
79
|
+
|
|
80
|
+
#### 5. Execute operation
|
|
81
|
+
|
|
82
|
+
- Issue the narrowest matching capability credential before executing.
|
|
83
|
+
- Use fully specified, non-interactive `gh` commands from [references/api-surface.md](references/api-surface.md).
|
|
84
|
+
- Use [references/common-use-cases.md](references/common-use-cases.md) only when you need a concrete command pattern.
|
|
85
|
+
- Check duplicates silently before creating a new issue. Only mention duplicates when relevant matches are actually found.
|
|
86
|
+
|
|
87
|
+
#### 6. Report result
|
|
88
|
+
|
|
89
|
+
- Return canonical issue URL, issue number, issue type, applied changes, and confidence.
|
|
75
90
|
- Include references used for verified claims.
|
|
91
|
+
- Keep routine issue-creation steps silent. Do not post progress chatter about duplicate checks, drafting, credential issuance, or command execution before the final result.
|
|
76
92
|
|
|
77
93
|
## Guardrails
|
|
78
94
|
|
|
95
|
+
### Execution
|
|
96
|
+
|
|
79
97
|
- Execute operations as soon as required fields are available. Do not pause for confirmation unless the user explicitly asks for preview/dry-run.
|
|
80
98
|
- Require explicit confirmation only for close/reopen or destructive broad rewrites.
|
|
81
|
-
-
|
|
99
|
+
- Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
|
|
100
|
+
|
|
101
|
+
### Quality
|
|
102
|
+
|
|
82
103
|
- Never claim verification without citing sources.
|
|
83
104
|
- For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
|
|
84
|
-
-
|
|
105
|
+
- If no relevant duplicates are found, continue directly to draft and create the issue, then report the created issue.
|
|
106
|
+
|
|
107
|
+
### Scope
|
|
108
|
+
|
|
109
|
+
- Issue workflows, pull request operations, and repository checkout. Do not execute repository admin mutations.
|
|
110
|
+
- Default to shallow clones. Do not use a full clone unless the task requires repository history or the user asks for it.
|
|
85
111
|
- If repository or installation access is missing, stop and return a concrete remediation message.
|
|
86
|
-
- Scope is issue workflows plus repository checkout. Do not execute pull-request or repository admin mutations in this skill.
|
|
@@ -1,37 +1,42 @@
|
|
|
1
1
|
# GitHub CLI API Surface
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
All operations use `gh` CLI. Commands must be deterministic and non-interactive.
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
## Authentication
|
|
6
|
+
|
|
7
|
+
Issue credentials with `jr-rpc issue-credential <capability>` before executing commands. The runtime handles token injection transparently.
|
|
6
8
|
|
|
7
9
|
## Capability to command mapping
|
|
8
10
|
|
|
9
|
-
| Capability
|
|
10
|
-
|
|
|
11
|
-
|
|
|
12
|
-
| `github.
|
|
13
|
-
| `github.issues.
|
|
14
|
-
| `github.issues.
|
|
15
|
-
| `github.
|
|
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.issues.comment` | `gh issue comment` |
|
|
18
|
+
| `github.labels.write` | `gh issue edit --add-label/--remove-label` |
|
|
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` |
|
|
16
21
|
|
|
17
22
|
## Command matrix
|
|
18
23
|
|
|
19
|
-
| Operation
|
|
20
|
-
|
|
|
21
|
-
| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1`
|
|
22
|
-
| Deepen shallow clone
|
|
23
|
-
| Convert shallow clone to full
|
|
24
|
-
| Create issue
|
|
25
|
-
| Update issue fields
|
|
26
|
-
| Close issue
|
|
27
|
-
| Reopen issue
|
|
28
|
-
| Add labels
|
|
29
|
-
| Remove labels
|
|
30
|
-
| Add comment
|
|
31
|
-
| Read issue
|
|
32
|
-
| Read comments
|
|
33
|
-
|
|
34
|
-
## Credential
|
|
24
|
+
| Operation | Command |
|
|
25
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------------------------- |
|
|
26
|
+
| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1` |
|
|
27
|
+
| Deepen shallow clone | `git -C DIRECTORY fetch --depth=N origin` |
|
|
28
|
+
| Convert shallow clone to full | `git -C DIRECTORY fetch --unshallow` |
|
|
29
|
+
| Create issue | `gh issue create --repo owner/repo --title "..." --body-file PATH` |
|
|
30
|
+
| Update issue fields | `gh issue edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]` |
|
|
31
|
+
| Close issue | `gh issue close NUMBER --repo owner/repo [--comment "..."]` |
|
|
32
|
+
| Reopen issue | `gh issue reopen NUMBER --repo owner/repo` |
|
|
33
|
+
| Add labels | `gh issue edit NUMBER --repo owner/repo --add-label LABEL [--add-label LABEL2]` |
|
|
34
|
+
| Remove labels | `gh issue edit NUMBER --repo owner/repo --remove-label LABEL [--remove-label LABEL2]` |
|
|
35
|
+
| Add comment | `gh issue comment NUMBER --repo owner/repo --body-file PATH` |
|
|
36
|
+
| Read issue | `gh issue view NUMBER --repo owner/repo --json number,title,state,labels,assignees,author,url,body` |
|
|
37
|
+
| Read comments | `gh api /repos/owner/repo/issues/NUMBER/comments --method GET --header "Accept: application/vnd.github+json"` |
|
|
38
|
+
|
|
39
|
+
## Credential and config helpers
|
|
35
40
|
|
|
36
41
|
Resolve repo default:
|
|
37
42
|
|
|
@@ -45,17 +50,23 @@ Set repo default:
|
|
|
45
50
|
jr-rpc config set github.repo owner/repo
|
|
46
51
|
```
|
|
47
52
|
|
|
48
|
-
Pass extra `git clone` flags after `--`:
|
|
49
|
-
|
|
50
|
-
```bash
|
|
51
|
-
gh repo clone owner/repo -- --depth=1 --filter=blob:none
|
|
52
|
-
```
|
|
53
|
-
|
|
54
53
|
Issue scoped credentials:
|
|
55
54
|
|
|
56
55
|
```bash
|
|
56
|
+
jr-rpc issue-credential github.contents.read --repo owner/repo
|
|
57
|
+
jr-rpc issue-credential github.contents.write --repo owner/repo
|
|
57
58
|
jr-rpc issue-credential github.issues.read
|
|
58
59
|
jr-rpc issue-credential github.issues.write
|
|
59
60
|
jr-rpc issue-credential github.issues.comment
|
|
60
61
|
jr-rpc issue-credential github.labels.write
|
|
62
|
+
jr-rpc issue-credential github.pull-requests.read
|
|
63
|
+
jr-rpc issue-credential github.pull-requests.write
|
|
61
64
|
```
|
|
65
|
+
|
|
66
|
+
## Behavior notes
|
|
67
|
+
|
|
68
|
+
- Prefer `--json` output for machine-readable parsing where available.
|
|
69
|
+
- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
|
|
70
|
+
- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
|
|
71
|
+
- For automation, always fully specify `gh issue create` with `--title` and `--body` or `--body-file`; never rely on interactive prompts.
|
|
72
|
+
- Return actionable errors for auth, permission, not-found, and validation failures.
|
|
@@ -4,15 +4,17 @@ Use these patterns as direct execution playbooks.
|
|
|
4
4
|
|
|
5
5
|
## 1) Clone a repository for local work
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
Issue credentials first, then default to a shallow clone:
|
|
8
8
|
|
|
9
9
|
```bash
|
|
10
|
+
jr-rpc issue-credential github.contents.read --repo owner/repo
|
|
10
11
|
gh repo clone owner/repo -- --depth=1
|
|
11
12
|
```
|
|
12
13
|
|
|
13
14
|
Clone into a specific directory:
|
|
14
15
|
|
|
15
16
|
```bash
|
|
17
|
+
jr-rpc issue-credential github.contents.read --repo owner/repo
|
|
16
18
|
gh repo clone owner/repo worktree/repo -- --depth=1
|
|
17
19
|
```
|
|
18
20
|
|
|
@@ -2,12 +2,6 @@
|
|
|
2
2
|
|
|
3
3
|
This skill runs in the harness sandbox (`node22`) and commands execute via the `bash` tool.
|
|
4
4
|
|
|
5
|
-
## Runtime environment
|
|
6
|
-
|
|
7
|
-
- Sandbox OS is Amazon Linux 2023.
|
|
8
|
-
- System packages are installed with `dnf`.
|
|
9
|
-
- Any package install command must run with root privileges (`sudo: true` in sandbox command execution).
|
|
10
|
-
|
|
11
5
|
## What is currently available
|
|
12
6
|
|
|
13
7
|
- Node runtime in sandbox (`node22` image).
|
|
@@ -15,24 +9,8 @@ This skill runs in the harness sandbox (`node22`) and commands execute via the `
|
|
|
15
9
|
- Outbound network access (default allow-all unless harness sets a network policy).
|
|
16
10
|
- Skill files are synchronized into `/vercel/sandbox/skills/<skill-name>`.
|
|
17
11
|
|
|
18
|
-
## Important constraint
|
|
19
|
-
|
|
20
|
-
Credentials should only be injected per command execution scope. Do not rely on global/session-wide environment for privileged tokens.
|
|
21
|
-
|
|
22
12
|
## Credential strategy
|
|
23
13
|
|
|
24
|
-
1.
|
|
25
|
-
|
|
26
|
-
|
|
27
|
-
- `github.issues.comment` for comments
|
|
28
|
-
- `github.labels.write` for label mutations
|
|
29
|
-
2. Runtime injects `Authorization` header transforms for `api.github.com`.
|
|
30
|
-
3. Execute `gh` CLI commands directly.
|
|
31
|
-
4. Do not persist tokens in files.
|
|
32
|
-
|
|
33
|
-
## Operational checks
|
|
34
|
-
|
|
35
|
-
- Verify CLI availability:
|
|
36
|
-
- `gh --version`
|
|
37
|
-
- Use non-interactive command flags in automation contexts.
|
|
38
|
-
- If 401/403 appears after credential issuance, reissue once, then stop with remediation guidance if still failing.
|
|
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.
|
|
@@ -1,54 +0,0 @@
|
|
|
1
|
-
# GitHub CLI Command Reference
|
|
2
|
-
|
|
3
|
-
All issue operations should go through `gh` CLI commands.
|
|
4
|
-
|
|
5
|
-
## Authentication
|
|
6
|
-
|
|
7
|
-
- Preferred: sandbox network policy injects Authorization headers for `api.github.com`.
|
|
8
|
-
- Optional local fallback: `GITHUB_TOKEN` (short-lived GitHub App installation token).
|
|
9
|
-
- If `GITHUB_TOKEN` is a host placeholder value, rely on header transforms and do not override it.
|
|
10
|
-
|
|
11
|
-
## Command shapes
|
|
12
|
-
|
|
13
|
-
### Create issue
|
|
14
|
-
|
|
15
|
-
`gh issue create --repo owner/repo --title "..." [--body-file /tmp/issue.md]`
|
|
16
|
-
|
|
17
|
-
### Update title/body
|
|
18
|
-
|
|
19
|
-
`gh issue edit 123 --repo owner/repo [--title "..."] [--body-file /tmp/issue.md]`
|
|
20
|
-
|
|
21
|
-
### Close issue
|
|
22
|
-
|
|
23
|
-
`gh issue close 123 --repo owner/repo [--comment "..."]`
|
|
24
|
-
|
|
25
|
-
### Reopen issue
|
|
26
|
-
|
|
27
|
-
`gh issue reopen 123 --repo owner/repo`
|
|
28
|
-
|
|
29
|
-
### Add labels
|
|
30
|
-
|
|
31
|
-
`gh issue edit 123 --repo owner/repo --add-label bug --add-label regression`
|
|
32
|
-
|
|
33
|
-
### Remove labels
|
|
34
|
-
|
|
35
|
-
`gh issue edit 123 --repo owner/repo --remove-label triage`
|
|
36
|
-
|
|
37
|
-
### Add comment
|
|
38
|
-
|
|
39
|
-
`gh issue comment 123 --repo owner/repo --body-file /tmp/comment.md`
|
|
40
|
-
|
|
41
|
-
### Get issue JSON
|
|
42
|
-
|
|
43
|
-
`gh issue view 123 --repo owner/repo --json number,title,state,labels,assignees,author,url,body`
|
|
44
|
-
|
|
45
|
-
### List comments JSON (read-only)
|
|
46
|
-
|
|
47
|
-
`gh api /repos/owner/repo/issues/123/comments --method GET --header "Accept: application/vnd.github+json"`
|
|
48
|
-
|
|
49
|
-
## Behavior notes
|
|
50
|
-
|
|
51
|
-
- Prefer `--json` output for machine-readable parsing where available.
|
|
52
|
-
- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
|
|
53
|
-
- Commands should be deterministic and non-interactive in harness usage.
|
|
54
|
-
- Return actionable errors for auth, permission, not-found, and validation failures.
|