GitHub Connector

SKILL.md

---
name: github-connector
description: "Interact with GitHub using the gh CLI. Use when the user wants to inspect issues and pull requests, check CI runs, review workflow failures, or run structured GitHub API queries."
metadata:
  polly:
    polly_managed_connector: true
    auth:
      - env: GITHUB_TOKEN
        type: api_key
        integration_id: github-pat
        description: GitHub Personal Access Token
    primaryEnv: GITHUB_TOKEN
---

# GitHub Connector

Use the `gh` CLI to interact with GitHub with user-scoped authentication.

## First-Time Setup

If GitHub is not connected yet, run:

`manage_auth(action="connect", integration_id="github-pat", auth_env="GITHUB_TOKEN")`

## Auth & Security

- Authentication is managed by Polly + Nango from `metadata.polly.auth`
- Never ask users to paste tokens in chat
- Never print or log token values
- Before running `gh`, map the injected token to `GH_TOKEN` in the same shell

## Preflight

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?missing GITHUB_TOKEN}" && gh auth status'
```

## Pull Requests

Check CI status on a PR:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh pr checks 55 --repo owner/repo'
```

List recent workflow runs:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh run list --repo owner/repo --limit 10'
```

View a run and failed steps:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh run view <run-id> --repo owner/repo --log-failed'
```

## Issues

List open issues:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh issue list --repo owner/repo --limit 20'
```

View an issue:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh issue view 123 --repo owner/repo'
```

## API for Advanced Queries

Get PR details with `gh api`:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh api repos/owner/repo/pulls/55 --jq ".title, .state, .user.login"'
```

## JSON Output

Use `--json` + `--jq` for structured output:

```bash
bash -lc 'export GH_TOKEN="${GITHUB_TOKEN:?}" && gh issue list --repo owner/repo --json number,title --jq ".[] | \"\\(.number): \\(.title)\""'
```

## Rules

- Always pass `--repo owner/repo` when not in a local git repository
- Prefer read-only commands unless the user explicitly asks for a write action
- If auth fails (401/403), run:
  `manage_auth(action="connect", integration_id="github-pat", auth_env="GITHUB_TOKEN")`