github

Files (1)

• SKILL.md

SKILL.md (first lines)

Use the `gh` CLI for everything. The user's token is exported as an env var
and `gh` reads it automatically — `gh auth status` will say "not logged in"
because gh keeps no config file in the sandbox, but every authenticated
subcommand works regardless. **The commands are identical in both modes**;
only the permission envelope differs, so check which one you're in before
diagnosing a `403`:

```sh
if [ -n "$GITHUB_TOKEN" ]; then echo "mode: pat (user-created token)"; \
elif [ -n "$GH_TOKEN" ]; then echo "mode: oauth"; \
else echo "no GitHub connection — connect at https://studio.acedata.cloud/console/connectors"; fi
```

Both are **secret — full account access within their scope. Never echo or
print them.**

`gh --help` and `gh <subcommand> --help` are always current. When unsure,
read the help first instead of guessing flags.

## Granted scopes — what you can and cannot do

**In PAT mode (`$GITHUB_TOKEN`)** the scopes are whatever the user picked
when they created the token, and a fine-grained token may be limited to a
few repositories. You cannot introspect them reliably — treat every `403` /
`404` as a possible permission limit and say so rather than retrying.

**In OAuth mode (`$GH_TOKEN`)** the connection requests exactly five scopes:
`read:user`, `user:email`, `repo`, `read:org`, `gist`. Everything in the
Recipes below fits inside them. These do NOT fit, and will fail no matter
how you phrase the call:

| Want to… | Needs scope | Verdict |
|---|---|---|
| Follow / unfollow a user | `user:follow` (or full `user`) | ✗ we only have `read:user` |
| Block / unblock a user | `user` | ✗ |
| Read / write Projects V2 | `read:project` / `project` | ✗ `INSUFFICIENT_SCOPES` |
| Manage SSH / GPG keys | `admin:public_key` / `admin:gpg_key` | ✗ |
| Manage org membership, teams | `write:org` / `admin:org` | ✗ read-only via `read:org` |
| Manage repo webhooks | `admin:repo_hook` | ✗ |

Users pick scopes at install time and every box is optional, so even the
five above may be partially granted. A `404` on something you know exists,
or a `403`, usually means a missing scope — not a wrong URL. Say so plainly
and point the user at `studio.acedata.cloud/console/connectors` to reconnect
with the box ticked (OAuth) or to paste a token with wider permissions (PAT).

## Two ways to call gh — prefer subcommands

### Style A: First-class subcommands — START HERE

`gh issue`, `gh pr`, `gh repo`, `gh search`, `gh release`, `gh workflow`,
`gh run`, `gh status`, `gh label`, `gh secret`, `gh variable`, `gh gist`,
`gh org`, `gh ruleset`. Use these whenever they cover the task; they
output formatted text by default and structured JSON via
`--json <fields> [--jq <expr>]`.

There is no `gh star` / `gh watch` subcommand — those go through
`gh api` (see below). `gh repo fork` does exist.

### Style B: Raw REST / GraphQL via `gh api`

`gh api <endpoint>` for REST, `gh api graphql -f query='…'` for GraphQL.
Useful when no first-class subcommand exists. Notable flags:

- `-X POST|PATCH|PUT|DELETE` — override method (default `GET`, becomes
  `POST` automatically when `-f`/`-F` is set).
- `-f key=value` — string field; `-F key=value` — JSON-typed field
  (`true`/`123`/`@file.json`); both URL-encode for `GET` and JSON-encode
  for body methods.
- `-q '<jq>'` — same as `--jq`. With a primitive top-level value (string
  / number) it prints the raw value (no quotes).
- `-H 'Accept: application/vnd.github.raw'` — fetch a file's raw bytes
  instead of the JSON wrapper.
- `--paginate` — auto-walk `Link: rel="next"`.

## Recipes

### Triage what's on my plate (issues + PRs + reviews + mentions)

```sh
gh status
```

### List recent issues in a repo

```sh
gh issue list --repo OWNER/REPO --limit 20
gh issue list --repo OWNER/REPO --state all --limit 20 \
  --json number,title,state,author,updatedAt,labels --jq '.[]'
```

### View an issue with comments

```sh
gh issue view 123 --repo OWNER/REPO --comments
gh issue view 123 --repo OWNER/REPO --json title,body,comments \
  --jq '{title, body, comments: [.comments[] | {author: .author.login, body, createdAt}]}'
```

### Create / comment / close an issue

```sh
gh issue create --repo OWNER/REPO --title "Bug: foo" --body "Repro steps…" --label bug
gh issue comment 123 --repo OWNER/REPO --body "LGTM"
gh issue close 123 --repo OWNER/REPO --comment "Fixed in #456"
gh issue reopen 123 --repo OWNER/REPO
```

### Edit an issue — labels, assignees, milestone, title, body

```sh
gh issue edit 123 --repo OWNER/REPO --add-label bug --add-assignee @me
gh issue edit 123 --repo OWNER/REPO --remove-label wontfix --milestone "v2.0"
gh issue edit 123 --repo OWNER/REPO --title "New title" --body "Rewritten body"
gh issue lock 123 --repo OWNER/REPO --reason spam
gh issue transfer 123 OWNER/OTHER_REPO --repo OWNER/REPO
```

`--add-project` / `--remove-project` need the `project` scope we do not

From AceDataCloud/Skills, Apache-2.0.

More from AceDataCloud/Skills