github-remote git:20260702.4d788fcA

Immutable. This exact content never changes and is served at /api/v1/blob/514b1fa48f49ae53.

---
name: github-remote
description: Safe remote GitHub operations via the gh CLI — account verification and switching, cloning, pushing, PR creation, reading/answering PR feedback, CI checks, and merging against the right account.
---

# GitHub Remote Skill

## Scope

Apply this skill whenever a task requires accessing, cloning, pushing to, or creating pull requests against remote GitHub repositories using the `gh` CLI:

- Identifying the correct GitHub account before any remote operation
- Switching accounts with `gh auth switch` before acting
- Cloning private repos, pushing branches, and creating PRs
- Verifying authentication state before acting

This skill does **not** cover local-only git operations (commits, branching, merging) — those require no account switching.

## The Target Account

The account to use is defined in the project's `.constellation/config.json` under `github.account`. Referred to as `<account>` below. If the config is missing or empty, ask the user which account to use — never guess.

---

## Verifying Authentication State

Before any remote operation:

```bash
gh auth status
```

To see just the currently active username:

```bash
gh api user --jq '.login'
```

---

## Switch-Then-Act Pattern

Every remote operation follows this exact sequence:

```bash
# Step 1 — switch to the configured account
gh auth switch --user <account>

# Step 2 — verify the switch succeeded
gh api user --jq '.login'   # must print <account>

# Step 3 — execute the intended operation
gh repo clone OWNER/REPO
```

Never skip step 2. A failed switch produces no error by default — verifying the active user confirms the switch succeeded before the operation runs against the wrong account.

---

## Core Operations

### Cloning a Repository

```bash
gh auth switch --user <account>
gh api user --jq '.login'
gh repo clone OWNER/REPO [path/to/local/directory]
```

`gh repo clone` configures the remote using the authenticated account's credentials automatically — no manual token handling.

### Viewing / Listing

```bash
gh repo view OWNER/REPO [--web]
gh repo list [OWNER --limit 50]
```

### Pushing Changes

`gh` manages authentication via the credential helper set up by `gh auth setup-git`. Switch accounts before pushing:

```bash
gh auth switch --user <account>
git push origin BRANCH_NAME
```

If the credential helper is not configured, run once per account (after switching to it):

```bash
gh auth setup-git
```

### Creating a Pull Request

Run from inside the repo directory — `gh` detects the remote context:

```bash
gh auth switch --user <account>

gh pr create \
  --title "feat: add invoice pagination" \
  --body "Adds cursor-based pagination to the invoice list endpoint." \
  --base main \
  --head BRANCH_NAME
```

Draft: `gh pr create --draft --title "WIP: …" --base main`

### Listing and Viewing PRs

```bash
gh pr list [--author "@me"]
gh pr view PR_NUMBER [--web]
gh pr checks PR_NUMBER
gh pr checkout PR_NUMBER
```

### Reading PR Feedback

```bash
# Issue-level comments + reviews, flattened (quick read)
gh pr view PR_NUMBER --comments

# Review threads with resolution state (the source of truth for "unresolved")
gh api graphql -f query='
  query($owner:String!, $repo:String!, $pr:Int!) {
    repository(owner:$owner, name:$repo) {
      pullRequest(number:$pr) {
        reviewThreads(first:100) { nodes {
          id isResolved path line
          comments(first:20) { nodes { author { login } body } }
        } }
      }
    }
  }' -f owner=OWNER -f repo=REPO -F pr=PR_NUMBER \
  --jq '.data.repository.pullRequest.reviewThreads.nodes[] | select(.isResolved | not)'
```

### Writing PR Feedback

```bash
# Top-level PR comment (e.g. the gate summary)
gh pr comment PR_NUMBER --body "..."

# Reply to a specific review comment
gh api repos/OWNER/REPO/pulls/PR_NUMBER/comments/COMMENT_ID/replies -f body="..."

# Resolve a review thread (after the fix is pushed and the reply posted)
gh api graphql -f query='
  mutation($thread:ID!) {
    resolveReviewThread(input:{threadId:$thread}) { thread { isResolved } }
  }' -f thread=THREAD_ID
```

### Waiting on CI and Merging

```bash
gh pr checks PR_NUMBER --watch      # blocks until all checks complete; non-zero exit on failure

gh pr merge PR_NUMBER --squash --delete-branch
```

Never merge with `--admin` (bypasses branch protection) and never use `--auto` without the
orchestrator's merge-policy preconditions being verified first.

---

## Troubleshooting

### Verify accounts are authenticated

`gh auth status` — if the configured account doesn't appear:

```bash
gh auth login --hostname github.com
```

### Permission denied on clone or push

Usually the wrong account is active:

```bash
gh api user --jq '.login'                      # shows wrong user?
gh auth switch --hostname github.com --user <account>
git push origin BRANCH_NAME                    # retry
```

### `gh auth switch` — account not found

The account is not authenticated. Run `gh auth login --hostname github.com`, then verify with `gh auth status` and retry.

---

## Hard Rules

- **Always switch to the configured account before any remote operation** — never assume the active account is correct
- **Always verify the switch** with `gh api user --jq '.login'` before the intended command
- **Never hardcode tokens or credentials** — `gh` manages authentication
- **Never run `gh repo clone`, `git push`, or `gh pr create` before confirming the active account**