@sentry/junior-github 0.68.0 → 0.70.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/SETUP.md +64 -17
- package/index.d.ts +41 -1
- package/index.js +975 -31
- package/package.json +3 -2
- package/permissions.js +77 -0
- package/skills/github-code/SKILL.md +6 -8
- package/skills/github-code/references/api-surface.md +43 -37
- package/skills/github-code/references/troubleshooting-workarounds.md +19 -14
- package/skills/github-issues/SKILL.md +5 -7
- package/skills/github-issues/references/api-surface.md +3 -3
- package/skills/github-issues/references/issue-examples.md +0 -28
- package/skills/github-issues/references/troubleshooting-workarounds.md +13 -12
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@sentry/junior-github",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.70.0",
|
|
4
4
|
"private": false,
|
|
5
5
|
"publishConfig": {
|
|
6
6
|
"access": "public"
|
|
@@ -20,10 +20,11 @@
|
|
|
20
20
|
"files": [
|
|
21
21
|
"index.d.ts",
|
|
22
22
|
"index.js",
|
|
23
|
+
"permissions.js",
|
|
23
24
|
"skills",
|
|
24
25
|
"SETUP.md"
|
|
25
26
|
],
|
|
26
27
|
"dependencies": {
|
|
27
|
-
"@sentry/junior-plugin-api": "0.
|
|
28
|
+
"@sentry/junior-plugin-api": "0.70.0"
|
|
28
29
|
}
|
|
29
30
|
}
|
package/permissions.js
ADDED
|
@@ -0,0 +1,77 @@
|
|
|
1
|
+
const LEVELS = new Set(["read", "write", "admin"]);
|
|
2
|
+
// GitHub documents these installation-token permission fields as write-only.
|
|
3
|
+
const WRITE_ONLY_PERMISSIONS = new Set(["profile", "workflows"]);
|
|
4
|
+
|
|
5
|
+
function isLevel(value) {
|
|
6
|
+
return LEVELS.has(value);
|
|
7
|
+
}
|
|
8
|
+
|
|
9
|
+
function normalizeScope(rawScope) {
|
|
10
|
+
return String(rawScope).trim().replace(/-/g, "_");
|
|
11
|
+
}
|
|
12
|
+
|
|
13
|
+
/** Validate configured GitHub App permissions before using them in grants. */
|
|
14
|
+
export function normalizePermissions(permissions) {
|
|
15
|
+
if (permissions === undefined) {
|
|
16
|
+
return undefined;
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
const entries = Object.entries(permissions);
|
|
20
|
+
if (entries.length === 0) {
|
|
21
|
+
throw new Error(
|
|
22
|
+
"githubPlugin appPermissions must contain at least one permission when provided.",
|
|
23
|
+
);
|
|
24
|
+
}
|
|
25
|
+
|
|
26
|
+
const request = {};
|
|
27
|
+
for (const [rawScope, rawLevel] of entries) {
|
|
28
|
+
const normalizedScope = normalizeScope(rawScope);
|
|
29
|
+
if (!normalizedScope) {
|
|
30
|
+
throw new Error(
|
|
31
|
+
"githubPlugin appPermissions contains an empty permission name.",
|
|
32
|
+
);
|
|
33
|
+
}
|
|
34
|
+
if (!/^[a-z][a-z0-9_]*$/.test(normalizedScope)) {
|
|
35
|
+
throw new Error(
|
|
36
|
+
`githubPlugin appPermissions contains invalid permission "${rawScope}".`,
|
|
37
|
+
);
|
|
38
|
+
}
|
|
39
|
+
if (!isLevel(rawLevel)) {
|
|
40
|
+
throw new Error(
|
|
41
|
+
`githubPlugin appPermissions.${rawScope} must be "read", "write", or "admin".`,
|
|
42
|
+
);
|
|
43
|
+
}
|
|
44
|
+
request[normalizedScope] = rawLevel;
|
|
45
|
+
}
|
|
46
|
+
return request;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/** Build the read-only installation-token permission body. */
|
|
50
|
+
export function readGrantPermissions(permissions) {
|
|
51
|
+
const readOnly = { metadata: "read" };
|
|
52
|
+
for (const [scope, level] of Object.entries(permissions ?? {})) {
|
|
53
|
+
if (!isLevel(level)) {
|
|
54
|
+
throw new Error(
|
|
55
|
+
`GitHub permission "${scope}" returned invalid level "${String(level)}".`,
|
|
56
|
+
);
|
|
57
|
+
}
|
|
58
|
+
if (!WRITE_ONLY_PERMISSIONS.has(scope)) {
|
|
59
|
+
readOnly[scope] = "read";
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return readOnly;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Expose configured permissions as plugin capabilities for host policy checks. */
|
|
66
|
+
export function permissionCapabilities(permissions) {
|
|
67
|
+
if (permissions === undefined) {
|
|
68
|
+
return undefined;
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
return Object.entries(permissions)
|
|
72
|
+
.map(([normalizedScope, rawLevel]) => {
|
|
73
|
+
const scope = normalizedScope.replace(/_/g, "-");
|
|
74
|
+
return `github.${scope}.${rawLevel}`;
|
|
75
|
+
})
|
|
76
|
+
.sort();
|
|
77
|
+
}
|
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: github-code
|
|
3
|
-
description: Clone repositories, inspect source, edit code, and manage pull requests with GitHub CLI. Use for repo implementation questions, cloning/editing, PR inspection/mutation, and PR
|
|
3
|
+
description: Clone repositories, inspect source, edit code, and manage pull requests with GitHub CLI. Use for repo implementation questions, cloning/editing, PR inspection/mutation, and PR creation order questions. For PR creation order, answer that the branch must be pushed before `gh pr create`. Prefer this skill for repository and code tasks even when the repo concerns Sentry products.
|
|
4
4
|
allowed-tools: bash
|
|
5
5
|
---
|
|
6
6
|
|
|
@@ -13,7 +13,7 @@ Use `gh` and `git` for repository checkout, source investigation, code changes,
|
|
|
13
13
|
| Need | Load |
|
|
14
14
|
| ----------------------------------- | -------------------------------------------------------------------------------------- |
|
|
15
15
|
| Command syntax, permissions, config | [references/api-surface.md](references/api-surface.md) |
|
|
16
|
-
| Failed commands,
|
|
16
|
+
| Failed commands, permission errors | [references/troubleshooting-workarounds.md](references/troubleshooting-workarounds.md) |
|
|
17
17
|
|
|
18
18
|
## Core rules
|
|
19
19
|
|
|
@@ -24,7 +24,7 @@ Use `gh` and `git` for repository checkout, source investigation, code changes,
|
|
|
24
24
|
- Do not overwrite or revert unrelated user changes.
|
|
25
25
|
- Do not guess architecture, upstream intent, or feedback validity without reading the relevant code, comments, or failing output.
|
|
26
26
|
- Do not claim checks ran unless they did. Do not declare a fix complete without running the chosen check or stating why no credible check was available.
|
|
27
|
-
- Stop on: missing repo access, ambiguous target, destructive op without confirmation, or unresolved
|
|
27
|
+
- Stop on: missing repo access, ambiguous target, destructive op without confirmation, or unresolved permission failure.
|
|
28
28
|
|
|
29
29
|
## Workflow
|
|
30
30
|
|
|
@@ -130,15 +130,14 @@ Defaults:
|
|
|
130
130
|
**Footers** (in order):
|
|
131
131
|
|
|
132
132
|
1. Issue references (`Fixes #N`, `Refs SENTRY-N`), if any.
|
|
133
|
-
2.
|
|
134
|
-
3. Session link — when `gen_ai.conversation.id` is available:
|
|
133
|
+
2. Session link — when `gen_ai.conversation.id` is available:
|
|
135
134
|
|
|
136
135
|
```
|
|
137
136
|
---
|
|
138
137
|
[View Session in Sentry](https://sentry.sentry.io/traces/?project=4510944073809921&query=gen_ai.conversation.id%3A%22<url-encoded conversation id>%22)
|
|
139
138
|
```
|
|
140
139
|
|
|
141
|
-
**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning reviewers or
|
|
140
|
+
**Assignment:** resolve GitHub handles from evidence (`gh api search/users`, org membership, repo history) before assigning requested reviewers or assignees. Skip assignment when the handle cannot be confirmed.
|
|
142
141
|
|
|
143
142
|
### 7. Report result
|
|
144
143
|
|
|
@@ -156,12 +155,11 @@ Before finishing, reconcile any plan or checklist stated earlier — mark items
|
|
|
156
155
|
|
|
157
156
|
**PR inspection** — read-only `gh pr` and `gh api` commands. Query both conversation comments (`--json comments`) and review comments (`gh api .../pulls/{n}/comments` and `.../reviews`).
|
|
158
157
|
|
|
159
|
-
**PR mutation** — push before create. Retry once on
|
|
158
|
+
**PR mutation** — push before create. Retry once on permission failure after verifying repo targeting. Treat merge, close-with-delete, and force-push as confirmation-required. No admin mutations.
|
|
160
159
|
|
|
161
160
|
## Guardrails
|
|
162
161
|
|
|
163
162
|
- Default shallow clones; deepen only when needed.
|
|
164
163
|
- Confirm before destructive merges or force operations.
|
|
165
164
|
- Answer source questions from repo evidence, not product framing or memory.
|
|
166
|
-
- GitHub App auth is host-managed; do not ask users to reconnect accounts.
|
|
167
165
|
- Stop and return concrete remediation on missing access or permissions.
|
|
@@ -8,45 +8,47 @@ When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc confi
|
|
|
8
8
|
Run `jr-rpc config get github.repo` as a standalone bash command. Never chain it with `cd`, `&&`, pipes, or a provider command.
|
|
9
9
|
Treat explicit repo flags as command-targeting safety rails, not as a credential-scoping mechanism.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## GitHub App permission guidance
|
|
12
12
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
| `github.actions.read`
|
|
16
|
-
| `github.actions.write`
|
|
17
|
-
| `github.contents.read`
|
|
18
|
-
| `github.contents.write`
|
|
19
|
-
| `github.
|
|
20
|
-
| `github.pull-requests.
|
|
13
|
+
| Permission capability | Commands |
|
|
14
|
+
| ------------------------------------------------------ | ------------------------------------------------------------------------------------ |
|
|
15
|
+
| `github.actions.read` | `gh run list`, `gh run view`, `gh run watch`, `gh workflow list`, `gh workflow view` |
|
|
16
|
+
| `github.actions.write` | `gh workflow run`, `gh run rerun`, `gh run cancel` |
|
|
17
|
+
| `github.contents.read` | `gh repo clone`, `git fetch` |
|
|
18
|
+
| `github.contents.write` | `git push`, REST Git database writes, `gh api` create/update contents, `gh pr merge` |
|
|
19
|
+
| `github.workflows.write` | Workflow-file changes under `.github/workflows` |
|
|
20
|
+
| `github.pull-requests.read` | `gh pr view`, `gh pr list`, `gh pr diff`, `gh pr checks` |
|
|
21
|
+
| `github.pull-requests.write` | `gh pr create --head <branch>` after explicit push, `gh pr edit`, `gh pr close` |
|
|
22
|
+
| `github.administration.write` + `github.contents.read` | `gh repo fork`; avoid for routine PR creation |
|
|
21
23
|
|
|
22
24
|
## Command matrix
|
|
23
25
|
|
|
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
|
-
| Check branch | `git -C DIRECTORY branch --show-current`
|
|
30
|
-
| Check worktree state | `git -C DIRECTORY status --short --branch`
|
|
31
|
-
| View commit log against base | `git -C DIRECTORY log BASE..HEAD --oneline`
|
|
32
|
-
| Diff against base | `git -C DIRECTORY diff BASE...HEAD`
|
|
33
|
-
| Create branch | `git -C DIRECTORY checkout -b BRANCH`
|
|
34
|
-
| Stage and commit | `git -C DIRECTORY add -A && git -C DIRECTORY commit -m "message"`
|
|
35
|
-
| Push branch before PR creation | `git -C DIRECTORY push -u origin BRANCH`
|
|
26
|
+
| Operation | Command |
|
|
27
|
+
| ---------------------------------- | ------------------------------------------------------------------------------------------------- |
|
|
28
|
+
| Clone repository (default shallow) | `gh repo clone owner/repo [DIRECTORY] -- --depth=1` |
|
|
29
|
+
| Deepen shallow clone | `git -C DIRECTORY fetch --depth=N origin` |
|
|
30
|
+
| Convert shallow clone to full | `git -C DIRECTORY fetch --unshallow` |
|
|
31
|
+
| Check branch | `git -C DIRECTORY branch --show-current` |
|
|
32
|
+
| Check worktree state | `git -C DIRECTORY status --short --branch` |
|
|
33
|
+
| View commit log against base | `git -C DIRECTORY log BASE..HEAD --oneline` |
|
|
34
|
+
| Diff against base | `git -C DIRECTORY diff BASE...HEAD` |
|
|
35
|
+
| Create branch | `git -C DIRECTORY checkout -b BRANCH` |
|
|
36
|
+
| Stage and commit | `git -C DIRECTORY add -A && git -C DIRECTORY commit -m "message"` |
|
|
37
|
+
| Push branch before PR creation | `git -C DIRECTORY push -u origin BRANCH` |
|
|
36
38
|
| Create pull request (draft) | `gh pr create --draft --repo owner/repo --head BRANCH --base BASE --title "..." --body-file PATH` |
|
|
37
|
-
| Update pull request | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]`
|
|
38
|
-
| Close pull request | `gh pr close NUMBER --repo owner/repo`
|
|
39
|
-
| Merge pull request | `gh pr merge NUMBER --repo owner/repo [--merge \| --squash \| --rebase]`
|
|
40
|
-
| View pull request | `gh pr view NUMBER --repo owner/repo [--json ...]`
|
|
41
|
-
| List pull requests | `gh pr list --repo owner/repo [--state open \| closed \| merged]`
|
|
42
|
-
| Diff pull request | `gh pr diff NUMBER --repo owner/repo`
|
|
43
|
-
| Check pull request status | `gh pr checks NUMBER --repo owner/repo`
|
|
44
|
-
| View PR review comments | `gh api repos/{owner}/{repo}/pulls/{number}/comments`
|
|
45
|
-
| View PR reviews | `gh api repos/{owner}/{repo}/pulls/{number}/reviews`
|
|
46
|
-
| Dispatch workflow | `gh workflow run WORKFLOW -R owner/repo --ref REF [-f key=value ...]`
|
|
47
|
-
| List workflow runs | `gh run list -R owner/repo --workflow WORKFLOW [--limit N] [--json ...]`
|
|
48
|
-
| View workflow run | `gh run view RUN_ID -R owner/repo [--json ...] [--log-failed]`
|
|
49
|
-
| Watch workflow run | `gh run watch RUN_ID -R owner/repo --exit-status`
|
|
39
|
+
| Update pull request | `gh pr edit NUMBER --repo owner/repo [--title "..."] [--body-file PATH]` |
|
|
40
|
+
| Close pull request | `gh pr close NUMBER --repo owner/repo` |
|
|
41
|
+
| Merge pull request | `gh pr merge NUMBER --repo owner/repo [--merge \| --squash \| --rebase]` |
|
|
42
|
+
| View pull request | `gh pr view NUMBER --repo owner/repo [--json ...]` |
|
|
43
|
+
| List pull requests | `gh pr list --repo owner/repo [--state open \| closed \| merged]` |
|
|
44
|
+
| Diff pull request | `gh pr diff NUMBER --repo owner/repo` |
|
|
45
|
+
| Check pull request status | `gh pr checks NUMBER --repo owner/repo` |
|
|
46
|
+
| View PR review comments | `gh api repos/{owner}/{repo}/pulls/{number}/comments` |
|
|
47
|
+
| View PR reviews | `gh api repos/{owner}/{repo}/pulls/{number}/reviews` |
|
|
48
|
+
| Dispatch workflow | `gh workflow run WORKFLOW -R owner/repo --ref REF [-f key=value ...]` |
|
|
49
|
+
| List workflow runs | `gh run list -R owner/repo --workflow WORKFLOW [--limit N] [--json ...]` |
|
|
50
|
+
| View workflow run | `gh run view RUN_ID -R owner/repo [--json ...] [--log-failed]` |
|
|
51
|
+
| Watch workflow run | `gh run watch RUN_ID -R owner/repo --exit-status` |
|
|
50
52
|
|
|
51
53
|
## Config helpers
|
|
52
54
|
|
|
@@ -59,8 +61,12 @@ jr-rpc config set github.repo owner/repo
|
|
|
59
61
|
|
|
60
62
|
- Prefer `--json` output for machine-readable parsing where available.
|
|
61
63
|
- Pass extra `git clone` flags after `--` (e.g. `gh repo clone owner/repo -- --depth=1`).
|
|
64
|
+
- A local `git commit` does not call GitHub. Pushing that commit does: `git push` requires `github.contents.write` on the target repo and requester write access.
|
|
65
|
+
- REST Git commit construction also requires `github.contents.write`: `POST /git/blobs`, `POST /git/trees`, `POST /git/commits`, `POST /git/refs`, and `PATCH /git/refs/{ref}`.
|
|
66
|
+
- If the commit changes workflow files under `.github/workflows`, expect `github.workflows.write` in addition to contents write.
|
|
62
67
|
- Before `gh pr create`, push the head branch explicitly, then use `--head` so `gh` does not trigger hidden push/fork behavior. That push requires GitHub write access to the remote.
|
|
63
|
-
-
|
|
64
|
-
-
|
|
68
|
+
- Do not use fork creation as the normal PR path. GitHub requires Administration write plus Contents read for `POST /repos/{owner}/{repo}/forks`, and the app must be installed on both source and destination accounts.
|
|
69
|
+
- If the explicit `git push` fails with 401/403 or another access/permission error, verify the repo context and retry once. If it still fails, load troubleshooting guidance and report the exact command failure.
|
|
70
|
+
- `gh pr edit` is not a single-permission command: title/body/base/reviewer changes need pull request write permission; label, assignee, and milestone changes need issue write permission (use the `github-issues` skill); project flags are outside the current GitHub App permission guidance.
|
|
65
71
|
- `gh pr close --comment` may need `github.issues.write` (use `github-issues`); `gh pr close --delete-branch` needs `github.contents.write`.
|
|
66
|
-
- Return actionable errors for
|
|
72
|
+
- Return actionable errors for access, permission, not-found, and validation failures.
|
|
@@ -2,23 +2,28 @@
|
|
|
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 "..."` from `gh` | CLI version too old or wrong binary in the plugin runtime. | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.
|
|
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
|
-
| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` 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 |
|
|
13
|
-
| `
|
|
14
|
-
| 403
|
|
15
|
-
| `
|
|
16
|
-
|
|
|
17
|
-
| `
|
|
5
|
+
| Symptom | Likely cause | Fix |
|
|
6
|
+
| ------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
7
|
+
| `unknown command "..."` from `gh` | CLI version too old or wrong binary in the plugin runtime. | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available. |
|
|
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
|
+
| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` 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 | Issued GitHub credentials were rejected upstream. | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup. |
|
|
13
|
+
| `junior-auth-required provider=github grant=user-write` | User-to-server OAuth is missing or stale for a write request. | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually. |
|
|
14
|
+
| `git push` fails with 401/403 or auth/permission output | Write permission is missing, app installation is too narrow, or remote is wrong. | Verify the remote and repo context, retry once, then confirm app permissions and installation scope if it still fails. |
|
|
15
|
+
| Bash result includes `permission_denied` with `source: "upstream"` | GitHub returned 403 after Junior injected the named grant. | Do not call this a Junior runtime block. Use the message, connected account, upstream target, grant requirements, accepted-permissions, and SSO fields to explain the GitHub denial. |
|
|
16
|
+
| 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. |
|
|
17
|
+
| `gh auth status` shows `Token scopes: none` | Expected for GitHub App user-to-server tokens. | Do not treat this as read-only proof. Use the failed command, `permission_denied.acceptedPermissions`, and GitHub App permissions instead. |
|
|
18
|
+
| `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 ...`. |
|
|
19
|
+
| `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 `git -C DIRECTORY fetch --unshallow` when full history is required. |
|
|
20
|
+
| `sandbox setup failed (dnf install gh failed ...)` | `gh` package not available from the plugin runtime dependency bootstrap. | Report the plugin runtime bootstrap failure; do not try to repair package installation from the skill workflow. |
|
|
18
21
|
|
|
19
22
|
## Retry guidance
|
|
20
23
|
|
|
21
24
|
- Retry once for transient transport failures after verifying repo context.
|
|
22
25
|
- Do not loop retries on repeated 401/403/404 validation errors.
|
|
23
|
-
-
|
|
26
|
+
- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work; treat `installation-read` failures as app installation or host environment setup.
|
|
27
|
+
- Do not describe `permission_denied` with `source: "upstream"` as Junior blocking the request. It means the egress proxy injected a credential, forwarded the request, and recorded GitHub's upstream 403. Prefer its `account` and `grant.requirements` fields over inference when explaining what to fix.
|
|
28
|
+
- Do not infer permission level from OAuth scopes. GitHub App user tokens report no OAuth scopes; GitHub App permissions and accepted-permissions headers are the useful evidence.
|
|
24
29
|
- For persistent permission problems, return explicit remediation and stop.
|
|
@@ -1,13 +1,13 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: github-issues
|
|
3
|
-
description: Create, update, comment on, label, and inspect GitHub issues via GitHub CLI with concise, evidence-backed content. Use when users ask to open, edit, view, close, reopen, or triage GitHub issues — including tracking bugs, features, or tasks. Prefer this skill over generic repository tools for issue operations; do not use for pull requests, branches, pushes, or PR
|
|
3
|
+
description: Create, update, comment on, label, and inspect GitHub issues via GitHub CLI with concise, evidence-backed content. Use when users ask to open, edit, view, close, reopen, or triage GitHub issues — including tracking bugs, features, or tasks. Prefer this skill over generic repository tools for issue operations; do not use for pull requests, branches, pushes, or PR creation order questions.
|
|
4
4
|
allowed-tools: bash
|
|
5
5
|
---
|
|
6
6
|
|
|
7
7
|
# GitHub Issue Operations
|
|
8
8
|
|
|
9
9
|
Issue create, update, comment, label, state, and inspection via `gh` CLI.
|
|
10
|
-
Use only for GitHub issues. For pull requests, branches, pushes, or PR
|
|
10
|
+
Use only for GitHub issues. For pull requests, branches, pushes, or PR creation order questions, load `github-code` instead.
|
|
11
11
|
|
|
12
12
|
## Reference loading
|
|
13
13
|
|
|
@@ -59,11 +59,11 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
59
59
|
- Compress source material. Research notes, hypotheses, or transcripts become a short summary + scoped bullets — never paste raw investigation into the body.
|
|
60
60
|
- Do not add desired outcome, expected behavior, or acceptance criteria unless the thread explicitly requests them.
|
|
61
61
|
- Preserve material source references inline.
|
|
62
|
-
- When the request originated from a Slack thread or any on-behalf-of context, append a final line `Action taken on behalf of <name>.` using the action requester's real name. The action requester is the current `<requester>` or the person who explicitly asked you to create/update the issue, not necessarily the original reporter.
|
|
63
62
|
|
|
64
|
-
**
|
|
63
|
+
**Source attribution:**
|
|
65
64
|
|
|
66
|
-
-
|
|
65
|
+
- GitHub records the issue creator natively; do not add body or footer text to identify who asked Junior to create the issue.
|
|
66
|
+
- If the person who originally reported or observed the problem differs from the issue creator, capture that with durable body text such as `Reported by Alice.` or `Raised by Alice during incident triage.`
|
|
67
67
|
- Attach screenshots from the thread as image links when present.
|
|
68
68
|
- Include code snippets, related issues, and related PRs only when they materially improve the issue.
|
|
69
69
|
|
|
@@ -72,7 +72,6 @@ Follow [references/research-rules.md](references/research-rules.md) for cross-ty
|
|
|
72
72
|
Before running the `gh` create/edit command, check each gate. If any fails, revise and re-check before executing:
|
|
73
73
|
|
|
74
74
|
- Title length ≤ 60 characters.
|
|
75
|
-
- Delegated-action footer is the last line when applicable, using the action requester's real name, not the reporter's name unless they are the same person.
|
|
76
75
|
- No session framing remains (channel refs, slash commands, @mentions, Slack thread IDs).
|
|
77
76
|
- Body structure matches complexity — no empty sections, no restated title, no raw research dump.
|
|
78
77
|
|
|
@@ -95,4 +94,3 @@ Run [references/issue-quality-checklist.md](references/issue-quality-checklist.m
|
|
|
95
94
|
- Do not overwrite issue fields unless explicitly requested. Prefer partial updates over full body replacement.
|
|
96
95
|
- For `bug` issues, do not present a fix as definitive unless root-cause evidence is explicit.
|
|
97
96
|
- If repository or installation access is missing, stop and return a concrete remediation message.
|
|
98
|
-
- GitHub App auth is host-managed; do not ask the user to reconnect a GitHub account.
|
|
@@ -8,9 +8,9 @@ When the user omits `owner/repo`, resolve `github.repo` first with `jr-rpc confi
|
|
|
8
8
|
Run `jr-rpc config get github.repo` as a standalone bash command. Never chain it with `cd`, `&&`, pipes, or a `gh` command.
|
|
9
9
|
Treat explicit repo flags as command-targeting safety rails, not as a credential-scoping mechanism.
|
|
10
10
|
|
|
11
|
-
##
|
|
11
|
+
## GitHub App permission guidance
|
|
12
12
|
|
|
13
|
-
|
|
|
13
|
+
| Permission capability | Commands |
|
|
14
14
|
| --------------------- | ------------------------------------------------------------------------------------------- |
|
|
15
15
|
| `github.issues.read` | `gh issue view`, `gh api /repos/.../comments` |
|
|
16
16
|
| `github.issues.write` | `gh issue create`, `gh issue edit`, `gh issue comment`, `gh issue close`, `gh issue reopen` |
|
|
@@ -43,4 +43,4 @@ jr-rpc config set github.repo owner/repo
|
|
|
43
43
|
- Use `gh api` for endpoints not fully covered by `gh issue` subcommands.
|
|
44
44
|
- For automation, always fully specify `gh issue create` with `--title` and `--body` or `--body-file`; never rely on interactive prompts.
|
|
45
45
|
- Keep `--repo owner/repo` explicit when working across repositories.
|
|
46
|
-
- Return actionable errors for
|
|
46
|
+
- Return actionable errors for access, permission, not-found, and validation failures.
|
|
@@ -45,8 +45,6 @@ Good structure — problem-specific sections:
|
|
|
45
45
|
> ## Workaround
|
|
46
46
|
>
|
|
47
47
|
> Retry wrapper that catches LockError and clears the dedup key (PR #32).
|
|
48
|
-
>
|
|
49
|
-
> Action taken on behalf of Jane Doe.
|
|
50
48
|
|
|
51
49
|
## Task example
|
|
52
50
|
|
|
@@ -66,28 +64,6 @@ Good scope — quantified and specific:
|
|
|
66
64
|
> | `processReaction` | scheduling only |
|
|
67
65
|
> | `processAction` | scheduling only |
|
|
68
66
|
> | `processMessage` | scheduling + thread ID normalization + lock retry |
|
|
69
|
-
>
|
|
70
|
-
> Action taken on behalf of Jane Doe.
|
|
71
|
-
|
|
72
|
-
## Distinct reporter/requester example
|
|
73
|
-
|
|
74
|
-
Bad attribution:
|
|
75
|
-
|
|
76
|
-
> The bot resolved the review thread even though the warning still applies.
|
|
77
|
-
>
|
|
78
|
-
> Action taken on behalf of Bojan Oro.
|
|
79
|
-
|
|
80
|
-
Good attribution:
|
|
81
|
-
|
|
82
|
-
> Warden can resolve its own review thread even when the underlying warning still appears valid and the PR remains blocked.
|
|
83
|
-
>
|
|
84
|
-
> Reported by Bojan Oro.
|
|
85
|
-
>
|
|
86
|
-
> - Observed on a PR where Warden left a review comment about a missing backport
|
|
87
|
-
> - The review thread was later marked resolved by the bot
|
|
88
|
-
> - The PR still showed a blocking warning
|
|
89
|
-
>
|
|
90
|
-
> Action taken on behalf of David Cramer.
|
|
91
67
|
|
|
92
68
|
## Feature example
|
|
93
69
|
|
|
@@ -111,8 +87,6 @@ Good framing — current state, gap, options:
|
|
|
111
87
|
> | --------------------------- | ---------------------------------- |
|
|
112
88
|
> | File watch + hot reload | Simple, but no atomicity guarantee |
|
|
113
89
|
> | Config service with polling | Consistent, but adds a dependency |
|
|
114
|
-
>
|
|
115
|
-
> Action taken on behalf of Jane Doe.
|
|
116
90
|
|
|
117
91
|
## Principles
|
|
118
92
|
|
|
@@ -132,5 +106,3 @@ Good framing — current state, gap, options:
|
|
|
132
106
|
- Speculative detail mixed into verified facts
|
|
133
107
|
- Dumping a list of URLs without inline context
|
|
134
108
|
- Session-specific content (slash commands, channel references, raw transcript framing, or unrelated user chatter)
|
|
135
|
-
- Conflating reporter and action requester when they differ
|
|
136
|
-
- Missing delegated attribution footer on user-requested issue creation
|
|
@@ -2,21 +2,22 @@
|
|
|
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 in the plugin runtime. | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available.
|
|
8
|
-
| `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
|
-
| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying.
|
|
10
|
-
| `GraphQL: Could not resolve to a Repository` | Repo slug is wrong or inaccessible. | Validate `owner/repo` and confirm app installation on target repository.
|
|
11
|
-
| 401 Unauthorized |
|
|
12
|
-
|
|
|
13
|
-
|
|
|
14
|
-
|
|
|
15
|
-
|
|
|
5
|
+
| Symptom | Likely cause | Fix |
|
|
6
|
+
| ------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
|
|
7
|
+
| `unknown command "issue"` from `gh` | CLI version too old or wrong binary in the plugin runtime. | Verify `gh --version`; if it is unavailable or too old, report that the GitHub plugin runtime dependency is not available. |
|
|
8
|
+
| `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
|
+
| Command affects or authenticates against the wrong repo | Stale `github.repo` default or authenticated command missing explicit repo. | Pass `--repo owner/repo` for the target repository, or update `github.repo` before retrying. |
|
|
10
|
+
| `GraphQL: Could not resolve to a Repository` | Repo slug is wrong or inaccessible. | Validate `owner/repo` and confirm app installation on target repository. |
|
|
11
|
+
| 401 Unauthorized | Issued GitHub credentials were rejected upstream. | Verify the target repo, then use the grant/auth signal to distinguish stale user OAuth from app installation or host env setup. |
|
|
12
|
+
| `junior-auth-required provider=github grant=user-write` | User-to-server OAuth is missing or stale for a write request. | Follow the private OAuth prompt; do not ask the user to paste or manage tokens manually. |
|
|
13
|
+
| 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. |
|
|
14
|
+
| 404 Not Found | Issue number or repo is wrong. | Validate repo + issue ID with `gh issue view NUMBER --repo owner/repo`. |
|
|
15
|
+
| `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. |
|
|
16
|
+
| Comment command fails with empty body | Body file missing/empty. | Ensure comment file exists and has content before `gh issue comment`. |
|
|
16
17
|
|
|
17
18
|
## Retry guidance
|
|
18
19
|
|
|
19
20
|
- Retry once for transient transport failures after verifying repo context.
|
|
20
21
|
- Do not loop retries on repeated 401/403/404 validation errors.
|
|
21
|
-
-
|
|
22
|
+
- Treat missing or stale `user-read`/`user-write` grants as private GitHub App OAuth work; treat `installation-read` failures as app installation or host environment setup.
|
|
22
23
|
- For persistent permission problems, return explicit remediation and stop.
|