# Github Repo Ops

> Audit and safely manage GitHub repositories with gh CLI. Use when Codex needs to verify gh availability, list repositories, inspect or accept one repository invitation, audit access, audit repository rulesets and branch protection, audit repository security posture, audit repository webhooks and deploy keys, audit repository environments and deployment gates, score public-repository discoverability, benchmark similar repositories, capture or compare aggregate traffic, preview and apply repository metadata or local README improvements, or prepare an ethical trilingual launch kit. Always distinguish Codex sandbox credential visibility from host Homebrew gh authentication; never request reauthentication from a sandbox-only failure.

- Skill: `xxvk/github-repo-ops` (Agent Skill, multi-file: 19 files)
- Install (CLI): `npx skillmds@latest add xxvk/github-repo-ops`
- Raw SKILL.md: https://api.skillmd.com/api/skills/xxvk/github-repo-ops/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: DevOps & Infra
- Author: xxvk (https://skillmd.com/u/xxvk)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/xxvk/github-repo-ops

---


# GitHub repository operations

## Non-negotiable `gh` authentication rule

> [!IMPORTANT]
> The user's normal macOS Terminal with Homebrew `gh` is the authority for authentication state. The Codex sandbox is not an authentication authority.

1. Treat `gh auth status` or `scripts/check-gh.sh` failure inside the Codex sandbox only as `sandbox_cannot_access_host_credential`. Never label it `invalid token`, `logged out`, or an account failure.
2. Never recommend or run `gh auth login`, `gh auth logout`, token replacement, or credential-store changes based only on a sandbox result.
3. If the user states that Homebrew `gh` works in Terminal, accept host authentication as verified and do not block the task on another sandbox authentication check.
4. Run GitHub operations requiring the host credential or network through an approved unsandboxed/host-terminal execution path. If unavailable, report the sandbox boundary and request the specific command output without asking the user to reauthenticate.
5. Recommend reauthentication only after the same repository-owned check fails in the user's normal macOS host terminal.

This rule overrides any generic instruction to stop when `gh` appears unauthenticated.

Use the bundled Shell entrypoints for deterministic GitHub CLI operations. They delegate to the Python core, which owns JSON parsing, validation, scoring, permission checks, safe writes, and aggregate traffic handling. Run them from any directory; set `GH_BIN` when a test or alternate gh binary is needed.

## Safe workflow

1. Run `scripts/check-gh.sh` in the intended execution environment. Apply the non-negotiable authentication rule above before interpreting any failure.
2. Run `scripts/list-repos.sh [OWNER]` to inspect repositories visible to the authenticated account. Set `GH_REPO_LIMIT` to change the default limit of 100.
3. Run `scripts/list-invitations.sh` to list only pending invitations granting `write` access. Treat the first column as the invitation ID and the second as `OWNER/REPOSITORY`.
4. Ask the user to identify the exact invitation ID and repository before changing access.
5. Run `scripts/accept-invitation.sh INVITATION_ID OWNER/REPOSITORY --confirm` only for the explicitly selected invitation. The script rechecks the ID, repository, and `write` permission before changing access. Never loop over all invitations or infer consent from the list.
6. Run `scripts/verify-access.sh INVITATION_ID OWNER/REPOSITORY` to confirm the invitation is no longer pending and the resulting permission is at least `WRITE`.
7. Run `scripts/access-audit.sh OWNER/REPOSITORY` to produce a read-only JSON report of direct collaborators, teams, outside collaborators, pending invitations, and write-level access.
8. Run `scripts/ruleset-audit.sh OWNER/REPOSITORY [--branch NAME]` to produce a read-only JSON report of repository and organization rulesets, the rulesets that actually apply to a branch, classic branch protection, and missing or risky branch-protection findings.
9. Run `scripts/security-audit.sh OWNER/REPOSITORY [--branch NAME]` to produce a read-only JSON report of GitHub Actions permissions, Dependabot configuration, Secret Scanning, Code Scanning, and branch-protection posture, with missing or risky security findings.
10. Run `scripts/webhook-audit.sh OWNER/REPOSITORY` and `scripts/deploy-key-audit.sh OWNER/REPOSITORY` to produce read-only JSON reports of repository webhooks and deploy keys, flagging insecure-SSL or inactive hooks and write-access, unverified, or unused keys.
11. Run `scripts/environment-audit.sh OWNER/REPOSITORY` to produce a read-only JSON report of repository environments and deployment gates, flagging unprotected environments, missing required-reviewers rules, and unrestricted deployment branches.
12. Run `scripts/sensitive-content-audit.sh --repo-path PATH` to scan the current workspace locally. It never scans Git history by default, never prints matches, and returns a non-zero status for high or critical findings.
13. Run `scripts/repository-standards-audit.sh --repo-path PATH` to inspect required files, English/Chinese/Japanese parity, version drift, local links, documented scripts, and line-count compliance.
14. Run `scripts/readme-experience-audit.sh --repo-path PATH` to inspect user-facing README structure, first-success instructions, examples, tables, permissions, and visual documentation signals.

The access, ruleset, security, webhook, deploy-key, and environment audits use repository collaborator, team, outside-collaborator, invitation, ruleset, branch-protection, Actions-permission, Dependabot, Secret Scanning, Code Scanning, webhook, deploy-key, environment, and deployment APIs. They require sufficient repository administration access; do not expose tokens, secrets, or key material in reports.

## Discoverability and growth workflow

1. Run `scripts/growth-state-init.sh OWNER/REPOSITORY --repo-path PATH` once. Store ignored machine-local artifacts only under `.github-repo-ops/`.
2. Run `scripts/discoverability-audit.sh OWNER/REPOSITORY --repo-path PATH`. Use `--profile auto` unless the user explicitly chooses `generic` or `skill`.
3. Run `scripts/peer-benchmark.sh OWNER/REPOSITORY --repo-path PATH`. Explain why each peer was selected; never rank similarity by Stars alone.
4. Run `scripts/traffic-snapshot.sh OWNER/REPOSITORY --repo-path PATH`. Treat unavailable owner-only traffic as a permission limitation, preserve public metrics, and never infer visitor identity.
5. Compare stored snapshots with `scripts/traffic-compare.sh BEFORE_JSON AFTER_JSON`. Report percentages only for at least seven complete non-overlapping dates and describe results as correlation, not causation.
6. Read [references/growth-plan-schema.md](references/growth-plan-schema.md), then generate metadata or README suggestions from the audit evidence. Keep facts, recommendations, and draft copy visibly separate.
7. Preview metadata with `scripts/apply-growth-metadata.sh OWNER/REPOSITORY PLAN_JSON`; add `--confirm` only after the user approves the exact plan. The script rejects baseline drift and verifies the resulting fields.
8. Preview a local README candidate with `scripts/apply-growth-readme.sh --repo-path PATH --candidate FILE`; add `--confirm` only after the user approves the diff. Never commit, push, or open a PR without separate authorization.
9. Run `scripts/launch-kit-context.sh OWNER/REPOSITORY --repo-path PATH`, then draft English, Simplified Chinese, and Japanese release, social, community, Awesome-list, pitch, and keyword copy. Social cards are trilingual: store the canonical card as `docs/social-card.md` (English), `docs/social-card_CN.md` (Simplified Chinese), and `docs/social-card_JP.md` (Japanese). Keep all publication actions draft-only and check each community's rules.

Use `--no-store` for a read-only stdout-only audit, benchmark, or traffic smoke test. Do not buy engagement, automate spam, fabricate users, exchange Stars, or claim anonymous traffic identifies people.

Sensitive-content reports are local-only. Treat embeddings and generated RAG artifacts as sensitive data; RAG is not a secrecy boundary. Do not publish a public knowledge artifact without a separate redaction, residual-scan, provenance, and authorization review.

## Development

Run `python3 -m unittest tests/test_growth.py` and `bash tests/test_scripts.sh` for local tests. They use a fake `gh` binary and do not contact GitHub. After changing a script or the Python core, exercise read-only entrypoints against the real authenticated account. Invitation acceptance, metadata changes, and README replacement require explicit user approval; metadata and README live-write tests are never implied by development validation.