GitHub (gh CLI)

Defaults & Constraints

• Use gh CLI for all GitHub interactions.
• Set GH_PAGER=cat for all gh calls to avoid interactive pagers.
• The repo is elastic/kibana; when not inside a local clone, prefer -R elastic/kibana for gh subcommands. For gh api, -R is not supported; use explicit repos/elastic/kibana/... endpoints or set GH_REPO=elastic/kibana when using {owner}/{repo} placeholders.
• Follow repository merge settings (squash/rebase/merge); do not enforce a merge strategy.
• Never merge into the base branch via CLI; merges happen via the GitHub UI.

First Actions

1. Resolve the exact target repo/object (PR, issue, comment thread, release) before mutating anything.

PR Targeting

• If the user uses implicit-current phrasing ("this PR", "current PR", "PR for this branch") and does not specify a PR URL/number, resolve the PR for the current branch: gh pr view --json number -q .number.
• Do not assume an unspecified GitHub task targets the current branch PR unless the wording clearly implies the current PR.

PR Workflow

• Always open PRs as draft: gh pr create --draft.
• Check CI status: gh pr checks.
• View PR details: gh pr view.
• View PR diff: gh pr diff.
• List PR files: gh pr diff --name-only.
• Read PR review comments: gh api repos/elastic/kibana/pulls/{number}/comments.

PR Creation

• Always ask which existing issue the PR should reference (do not invent issue numbers).
• Ask the user whether the PR should Closes #X or Addresses #X before creating the PR.
• If there is no existing issue, stop and ask whether to create one; do NOT create issues unless the user explicitly instructs you to.
• PR title is a human-readable change summary (not necessarily the Conventional Commit header).

Issue Workflow

• View an issue: gh issue view {number}.
• Search issues: gh issue list --search "query".
• Create an issue: gh issue create.

Approvals

• Any GitHub side effect requires explicit approval unless the user instructed otherwise. Examples (non-exhaustive): create/edit PRs or issues, post comments/reviews, apply metadata (labels/assignees/milestones/projects), merge, or create releases.

PR Reviews

Read [references/review.md](references/review.md) before creating or modifying any PR review. It contains mandatory instructions for comment anchoring, verification, and avoiding irreversible API mistakes.

Core Rule: Pending vs Published

• Never include event in a review-creation payload (POST /repos/{o}/{r}/pulls/{n}/reviews). Without event the review stays PENDING; with it, the review is immediately and irreversibly published.
• Always create reviews via gh api repos/{o}/{r}/pulls/{n}/reviews --input <file> with the body in a JSON file. Do not pass -f event=... or -F event=... to the review-creation endpoint — every quoting form (bare, single-quoted, double-quoted, whole-pair quoted, $(...), backticks, ${VAR:-...}) is denied by the strip-review-event hook because the only safe sanitisation is parsing the JSON file.
• Verify the JSON file contains no top-level "event" key before submitting.
• To publish a review, use the separate submission endpoint: POST /repos/{o}/{r}/pulls/{n}/reviews/{id}/events with -f event=APPROVE (or COMMENT / REQUEST_CHANGES). The hook only denies event= on the review-creation endpoint, not on submission.

Posting PR Review Comments

See [references/review.md](references/review.md) for inline, file-level, threaded reply, and PR-level comment examples.

Advanced / API

• For anything beyond standard gh subcommands, use gh api with the GitHub REST or GraphQL endpoints.
• Multiline bodies/comments: use bash/zsh $'...' so \n becomes real newlines. Do NOT rely on \\n escapes inside normal quotes (especially gh api -f body=...).
• Payloads with arrays: prefer gh api ... --input /path/to/payload.json over -f/-F flags to avoid shell escaping issues.
• If you need to add query params to a GET gh api call, use -X GET. In practice, adding -f or -F without -X GET can cause gh to hit the POST schema by default.
• zsh gotcha: avoid unquoted ?ref=... in endpoints (triggers no matches found). Prefer: gh api -X GET repos/elastic/kibana/contents/PATH -F ref=main.

Output & Verification

• Before each side effect, restate the exact target and action you are about to perform.
• After each side effect, verify via read-back (gh/API) and report the URL, identifier, or resulting state.

Do not add/modify repo .github/* templates unless the user explicitly asks.

Sub-Issues API

GitHub's sub-issue API creates real parent-child relationships (not tasklists).

Create hierarchy:

1. Create child issues first with full descriptions.
2. Get GraphQL IDs:

``bash gh api graphql -f query='{ repository(owner:"elastic",name:"kibana") { issue(number:N) { id } } }' ``

1. Link:

``bash gh api graphql -f query="mutation { addSubIssue(input:{issueId:\"PARENTID\",subIssueId:\"CHILDID\"}) { issue { number } } }" ``

1. Verify: gh api repos/elastic/kibana/issues/NUM/sub_issues

Mutations: addSubIssue, removeSubIssue, reprioritizeSubIssue