---
name: github
description: Operate GitHub repositories, workflows, and PRs efficiently. Use
  for Actions optimization, PR hygiene, repo maintenance, and team collaboration
  patterns.
metadata:
  category: user-invoked
disable-model-invocation: true
---

## Pi Context-Aware Execution

When this skill is invoked in Pi, treat the user's current request and any skill arguments as the task input. Do not treat this file as the task by itself.

Before applying the skill, establish only the context needed for the request:

1. Identify the current working directory and relevant project scope.
2. Read local guidance first when present: AGENTS.md, CLAUDE.md, TODO.md, or nearby task/spec files.
3. Inspect the current codebase with targeted searches (prefer rg) and read relevant files before making claims or proposing changes.
4. Ground findings and recommendations in project evidence: cite file paths, commands, tests, docs, or external sources as applicable.
5. Ask a concise clarification only when the arguments and codebase context are insufficient to proceed safely.

Operate conservatively: avoid broad scans, large reads, subagents, or parallel fanout unless the user's requested depth clearly requires them.
Default output: return only the result, blockers, and required evidence. Omit preambles, process narration, repeated context, confidence scores, and follow-up offers. Use at most five bullets unless a required artifact or schema needs more.

# GitHub Operations

## Current Versions (Verify Before Use)

```bash
gh --version                      # GitHub CLI
act --version                     # Local Actions runner (optional)
```

Check [GitHub CLI releases](https://github.com/cli/cli/releases) and [GitHub Actions runner releases](https://github.com/actions/runner/releases).

## Core Principles

1. **PRs are the unit of review.** Every change goes through a PR. No direct pushes to main.
2. **Actions are code.** Workflows get the same review as application code.
3. **Branch protection is mandatory.** Main requires: PR, review, passing checks, up-to-date branch.
4. **gh CLI over web UI.** Scriptable, reproducible, faster.

## PR Hygiene Checklist

- [ ] PR title describes *what* and *why* (not just the ticket number)
- [ ] Description links to issue/ticket, summarizes changes, includes screenshots for UI
- [ ] Branch is up-to-date with main (rebased or merged)
- [ ] Checks are green before requesting review
- [ ] Reviewers assigned explicitly (not just "anyone")
- [ ] PR is small enough to review in < 20 minutes (~250 lines max)

## gh CLI Patterns

```bash
# Create PR from current branch
gh pr create --title "feat: add OAuth2 login" --body-file .github/PULL_REQUEST_TEMPLATE.md

# View checks
gh pr checks --watch --fail-fast

# Checkout a PR for local review
gh pr checkout 123

# View PR diff with comments
gh pr view 123 --comments

# Merge when green
gh pr merge --squash --delete-branch

# Review from CLI
gh pr review 123 --approve --body "LGTM"
```

## Actions Optimization

### Caching
```yaml
- uses: actions/cache@v4
  with:
    path: ~/.npm
    key: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
```

### Matrix Strategy
```yaml
strategy:
  fail-fast: false
  matrix:
    node: [20, 22]
    os: [ubuntu-latest]
```

### Reusable Workflows
```yaml
jobs:
  ci:
    uses: ./.github/workflows/reusable-ci.yml
    with:
      node-version: 22
    secrets: inherit
```

## Common Anti-Patterns

| Anti-Pattern | Why It's Wrong | Fix |
|---|---|---|
| `actions/checkout@v2` | Deprecated, security risks | Use `actions/checkout@v4` |
| `set-output` command | Deprecated | Use `GITHUB_OUTPUT` env file |
| `save-state` / `set-env` | Security vulnerability | Use `GITHUB_STATE` / `GITHUB_ENV` |
| No timeout on jobs | Runaway jobs burn minutes | `timeout-minutes: 10` |
| `pull_request_target` without care | Can expose secrets to forks | Use `pull_request` for untrusted code |
| Hardcoded secrets in workflows | Leaked in logs, not rotatable | Use GitHub Secrets + environments |
| `permissions: write-all` | Overprivileged workflows | Explicit `permissions` block |

## Validation Checklist

- [ ] `.github/workflows/` files pass `actionlint` or `yamllint`
- [ ] All `uses:` references are pinned to major version or SHA
- [ ] `permissions:` is explicitly defined (not default write-all)
- [ ] No secrets in workflow files (use `${{ secrets.XXX }}`)
- [ ] Jobs have `timeout-minutes`
- [ ] Reusable workflows are used for duplicated logic
- [ ] Branch protection rules enforce required checks

## Official Resources

- [GitHub Actions docs](https://docs.github.com/en/actions)
- [GitHub CLI manual](https://cli.github.com/manual/)
- [Security hardening for Actions](https://docs.github.com/en/actions/security-guides/security-hardening-for-github-actions)
- [Reusable workflows](https://docs.github.com/en/actions/sharing-automations/reusing-workflows)