github

すべての操作に gh CLI を使用してください。ユーザーのトークンは環境変数としてエクスポートされており、gh が自動的に読み取ります。サンドボックス内には gh の設定ファイルがないため、gh auth status は「not logged in」と表示しますが、認証が必要なサブコマンドはすべてそのまま動作します。どちらのモードでもコマンドは同じです。異なるのは権限の範囲だけなので、403 の原因を調べる前に、どちらのモードか確認してください。

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

どちらも秘密情報であり、その権限の範囲内でアカウント全体にアクセスできます。絶対にエコーしたり、表示したりしないでください。

gh --help と gh <subcommand> --help の内容は常に最新です。迷ったときはフラグを推測せず、まずヘルプを読んでください。

許可されているスコープ — できること、できないこと

PAT モード（$GITHUB_TOKEN）の場合、スコープはユーザーがトークン作成時に選択したものです。また、きめ細かい権限を設定したトークンでは、対象が少数のリポジトリに限られる場合があります。スコープを確実に調べることはできません。すべての 403／404 は権限の制限による可能性があるものとして扱い、再試行するのではなく、その旨を伝えてください。

OAuth モード（$GH_TOKEN）の場合、接続時に要求するスコープは read:user、user:email、repo、read:org、gist の5つです。以下のレシピにある操作はすべてこの範囲内です。次の操作は範囲外のため、呼び出し方をどう変えても失敗します。

操作	必要なスコープ	判定
ユーザーをフォロー／フォロー解除する	user:follow（または完全な user）	✗ read:user しかありません
ユーザーをブロック／ブロック解除する	user	✗
Projects V2 を読み取り／書き込みする	read:project／project	✗ INSUFFICIENT_SCOPES
SSH／GPG キーを管理する	admin:public_key／admin:gpg_key	✗
組織のメンバーシップやチームを管理する	write:org／admin:org	✗ read:org による読み取り専用です
リポジトリの Webhook を管理する	admin:repo_hook	✗

ユーザーはインストール時にスコープを選択します。チェックボックスはすべて任意なので、上記の5つが一部しか許可されていない場合もあります。存在することがわかっているものへの 404 や 403 は、URL の誤りではなく、通常はスコープの不足を意味します。そのことを明確に伝え、OAuth の場合は必要なチェックボックスをオンにして studio.acedata.cloud/console/connectors から再接続するよう、PAT の場合はより広い権限を持つトークンを貼り付けるよう案内してください。

gh の呼び出し方は2通り — サブコマンドを優先してください

スタイル A：専用サブコマンド — まずはこちらを使用

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 を使用してください。タスクに対応するサブコマンドがある場合は、そちらを使ってください。出力はデフォルトで整形済みテキストになり、--json <fields> [--jq <expr>] を使うと構造化 JSON で取得できます。

gh star／gh watch サブコマンドはありません。これらの操作には gh api を使用してください（以下を参照）。gh repo fork はあります。

スタイル B：gh api による REST／GraphQL の直接呼び出し

REST には gh api <endpoint>、GraphQL には gh api graphql -f query='…' を使用します。専用サブコマンドがない場合に便利です。主なフラグは次のとおりです。

• -X POST|PATCH|PUT|DELETE — メソッドを指定します（デフォルトは GET で、-f／-F を設定すると自動的に POST になります）。
• -f key=value — 文字列フィールドです。-F key=value — JSON 型フィールドです（true／123／@file.json）。どちらも GET では URL エンコードされ、本文を使うメソッドでは JSON エンコードされます。
• -q '<jq>' — --jq と同じです。トップレベルの値がプリミティブ型（文字列／数値）の場合、値がそのまま出力されます（引用符は付きません）。
• -H 'Accept: application/vnd.github.raw' — JSON ラッパーではなく、ファイルの生データを取得します。
• --paginate — Link: rel="next" を自動的にたどります。

レシピ

自分の対応事項を確認する（Issue ＋ PR ＋レビュー ＋メンション）

gh status

リポジトリの最近の Issue を一覧表示する

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 '.[]'

コメント付きで Issue を表示する

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}]}'

Issue を作成／コメント／クローズする

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

Issue を編集する — ラベル、担当者、マイルストーン、タイトル、本文

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 には、使用できない project スコープが必要です。そのため、これらの操作は失敗します。このリストにあるその他の操作はすべて使用できます。

自分に割り当てられた PR／自分が作成した PR を一覧表示する

gh search prs --assignee=@me --state=open --json number,title,repository,updatedAt
gh search prs --author=@me --state=open
gh search prs --review-requested=@me --state=open

差分と CI チェック付きで PR を表示する

gh pr view 456 --repo OWNER/REPO
gh pr diff 456 --repo OWNER/REPO
gh pr checks 456 --repo OWNER/REPO

PR を作成／編集する

gh pr create --repo OWNER/REPO --base main --head feature-branch \
  --title "Add foo" --body "Closes #123" --draft
gh pr edit 456 --repo OWNER/REPO --add-reviewer octocat --add-label review-needed
gh pr edit 456 --repo OWNER/REPO --base develop --title "Retitled"
gh pr ready 456 --repo OWNER/REPO          # draft → ready for review

PR にコメントする／レビューする／マージする

gh pr comment 456 --repo OWNER/REPO --body "Please rebase on main."
gh pr review 456 --repo OWNER/REPO --approve --body "LGTM"
gh pr review 456 --repo OWNER/REPO --request-changes --body "See nits"
gh pr merge 456 --repo OWNER/REPO --squash --delete-branch
gh pr update-branch 456 --repo OWNER/REPO  # merge base into the PR branch
gh pr close 456 --repo OWNER/REPO

merge、close、review --approve は取り消せない操作、または一般に公開される操作です。ユーザーがその操作を明確に依頼していない限り、実行前に確認してください。

リポジトリにスターを付ける／外す

gh のサブコマンドはありません。REST ルートを使用してください。204 は成功を意味し、スターが付いている場合、GET は 204 を返し、付いていない場合は 404 を返します。

gh api -X PUT    user/starred/OWNER/REPO      # star
gh api -X DELETE user/starred/OWNER/REPO      # unstar
gh api           user/starred/OWNER/REPO      # 204 = starred, 404 = not
gh api user/starred --paginate --jq '.[].full_name'   # list my stars

リポジトリをウォッチする／解除する（通知の購読）

gh api -X PUT repos/OWNER/REPO/subscription -F subscribed=true    # watch
gh api -X PUT repos/OWNER/REPO/subscription -F ignored=true       # ignore
gh api -X DELETE repos/OWNER/REPO/subscription                    # unwatch
gh api user/subscriptions --paginate --jq '.[].full_name'

ウォッチとスターは別の機能です。スターは公開ブックマークであり、ウォッチはユーザーの通知に届く内容だけを変更します。

リポジトリをフォークする

gh repo fork OWNER/REPO --clone=false
gh repo fork OWNER/REPO --org MY_ORG --default-branch-only
gh api repos/OWNER/REPO/forks --jq '.[].full_name'

スターとフォークはユーザーの公開プロフィールに表示されます。明示的に依頼されていない限り、他のユーザーのリポジトリでどちらかを行う前に確認してください。

通知

gh api notifications --jq '.[] | "\(.repository.full_name) \(.subject.type) \(.subject.title)"'
gh api -X PATCH notifications                                # mark all read
gh api -X PATCH notifications/threads/<THREAD_ID>            # mark one read

リポジトリを作成／管理する

gh repo create OWNER/NEW_REPO --private --description "…"
gh repo view OWNER/REPO --json description,url,stargazerCount,defaultBranchRef
gh repo edit OWNER/REPO --description "New desc" --add-topic ai --visibility private
gh repo list OWNER --limit 30 --json name,visibility,updatedAt
gh repo archive OWNER/REPO --yes

gh repo delete には delete_repo が必要ですが、これは許可されていないため、失敗します。絶対に使用しないでください。

リリース

gh release list --repo OWNER/REPO --limit 10
gh release view v1.2.0 --repo OWNER/REPO
gh release create v1.2.0 --repo OWNER/REPO --title "v1.2.0" --notes "Changelog…"
gh release create v1.2.0 --repo OWNER/REPO --generate-notes ./dist/app.zip
gh release upload v1.2.0 ./extra-asset.tar.gz --repo OWNER/REPO
gh release download v1.2.0 --repo OWNER/REPO --pattern '*.zip'

Gist

gh gist list --limit 20
gh gist create ./script.py --public --desc "Handy script"
gh gist view <GIST_ID>
gh gist edit <GIST_ID>
gh gist delete <GIST_ID>

ラベルとマイルストーン

gh label list --repo OWNER/REPO
gh label create urgent --repo OWNER/REPO --color FF0000 --description "Drop everything"
gh label edit bug --repo OWNER/REPO --color 00FF00
gh label clone SOURCE_OWNER/SOURCE_REPO --repo OWNER/REPO

# Milestones have no gh subcommand — use the API
gh api repos/OWNER/REPO/milestones --jq '.[] | "\(.number) \(.title) \(.open_issues) open"'
gh api -X POST repos/OWNER/REPO/milestones -f title="v2.0" -f due_on="2026-12-31T23:59:59Z"

ブランチ、コミット、比較

gh api repos/OWNER/REPO/branches --jq '.[].name'
gh api "repos/OWNER/REPO/commits?per_page=20" \
  --jq '.[] | "\(.sha[0:7]) \(.commit.author.date) \(.commit.message | split("\n")[0])"'
gh api repos/OWNER/REPO/compare/main...feature-branch \
  --jq '{ahead: .ahead_by, behind: .behind_by, files: [.files[].filename]}'
gh api -X DELETE repos/OWNER/REPO/git/refs/heads/stale-branch

リポジトリ内のファイルを読み込む／書き込む

# Read raw bytes, no base64 dance
gh api "repos/OWNER/REPO/contents/path/to/file.ts" \
  -H 'Accept: application/vnd.github.raw'

# Write requires base64 content + the current blob sha when replacing
SHA=$(gh api repos/OWNER/REPO/contents/README.md --jq .sha)
gh api -X PUT repos/OWNER/REPO/contents/README.md \
  -f message="docs: update readme" \
  -f content="$(base64 < ./README.md | tr -d '\n')" \
  -f sha="$SHA"

GitHub 全体を検索する

gh search code 'someFunction language:typescript' --limit 20 \
  --json repository,path,url --jq '.[] | "\(.repository.nameWithOwner) \(.path)"'
gh search repos 'topic:mcp stars:>100' --limit 20 --json fullName,stargazersCount
gh search commits 'fix memory leak' --repo OWNER/REPO --limit 10
gh search issues 'is:open label:bug' --owner OWNER --limit 20

Actions ワークフローを実行／確認する

gh workflow list --repo OWNER/REPO
gh workflow run ci.yaml --repo OWNER/REPO --ref main -f key=value
gh run list --repo OWNER/REPO --workflow ci.yaml --limit 5
gh run view <RUN_ID> --repo OWNER/REPO --log-failed
gh run rerun <RUN_ID> --repo OWNER/REPO --failed
gh run cancel <RUN_ID> --repo OWNER/REPO
gh run watch <RUN_ID> --repo OWNER/REPO

Actions のシークレットと変数

gh secret list --repo OWNER/REPO
gh secret set MY_TOKEN --repo OWNER/REPO --body "value"
gh variable list --repo OWNER/REPO
gh variable set MY_VAR --repo OWNER/REPO --body "value"

シークレットの値は書き込み専用です。設定と名前の一覧表示はできますが、値を読み戻すことはできません。ユーザーから渡されたシークレットをコメント、イシュー、コミットに絶対に出力しないでください。

Organization（read:org の読み取り専用）

gh org list
gh api user/orgs --jq '.[].login'
gh api orgs/ORG/members --jq '.[].login'
gh api orgs/ORG/repos --paginate --jq '.[].full_name'

REST ではできない操作に GraphQL を使う

gh api graphql -f query='
  query($owner: String!, $repo: String!, $num: Int!) {
    repository(owner: $owner, name: $repo) {
      issue(number: $num) {
        title
        timelineItems(first: 50) {
          nodes { __typename ... on CrossReferencedEvent { source { ... on PullRequest { number title state } } } }
        }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F num=123

Projects V2 は GraphQL でのみ利用でき、read:project が必要です。これは許可されていないため、これらのクエリは INSUFFICIENT_SCOPES を返します。これを前提とした手順を作成しないでください。

注意事項

• プライベートリポジトリでは、ユーザーが studio.acedata.cloud/console/connectors で接続を認証した際に、repo スコープを許可している必要があります。存在するとわかっているリポジトリで 404 が返される場合は、URL が間違っているのではなく、通常はスコープが不足しています。
• --json がフィールド名を受け付けない場合、gh は有効なフィールド名をすべて表示します。エラーを読み直し、そこから選んでください。
• gh issue list --search と gh search issues では、GitHub の検索構文（is:open、assignee:@me、repo:owner/name など）が使われます。複数のリポジトリを横断して検索するには gh search issues／gh search prs を使用し、単一のリポジトリでは gh issue list を使用してください。
• gh api --paginate が機能するのは、Link ヘッダーを返すエンドポイントだけです。カーソル方式でページネーションするエンドポイントでは、pagination.next を自分でたどる必要があります。
• リクエスト本文を必要としない書き込みエンドポイント（スター、フォロー、ウォッチ解除）は、成功時に 204 No Content を返します。レスポンスが空なのは成功を意味し、失敗ではありません。
• この接続はスケジュールされたタスクで無人実行される場合があります。公開アクション（スター、フォーク、イシュー／PR へのコメント、レビュー、マージ）は、ユーザーのアカウントに永続的に残り、公開されてユーザーに帰属する履歴になります。無人実行では、タスクで許可された操作だけを厳守してください。