Gh CLI Ops

Gh Cli Ops

Overview

Use gh + git to manage GitHub repositories, automation, and releases with repeatable, safe workflows.

Quick start (context)

1. Use the wrapper so commands are logged: scripts/ghx auth status, scripts/ghx repo view, git status -sb.
2. Identify the task category and use the matching section or the command map in references/gh-command-map.md.
3. Prefer JSON output (--json ... --jq ...) for scripted reads; ask before destructive changes (delete, merge, release delete, secret overwrite).
4. Review references/auto-summary.md to adapt based on recent successes/failures.

Automation wrapper (required)

• Use scripts/ghx for all gh commands to log outcomes to references/usage-log.jsonl.
• The wrapper auto-updates references/auto-summary.md after each command to capture what worked or failed.
• If you must run gh directly (e.g., debugging), run scripts/track_command.sh gh ... afterward with the same args.

Task map

See references/gh-command-map.md for a task-to-command mapping and safe defaults.

Workflows & runs

• Use gh workflow list/view/run to inspect or trigger workflows. Ensure the workflow supports on: workflow_dispatch before running.
• Provide inputs via -f/-F or --json when needed; confirm expected inputs from the workflow file.
• Use gh run list/view/watch/rerun/download to monitor or re-run jobs; use gh run view --log/--log-failed for logs.
• For deploys, identify the deploy workflow and trigger it via gh workflow run with the correct --ref and inputs.
• If gh workflow run fails with HTTP 403 and Resource not accessible by integration, check for GITHUB_TOKEN or GH_TOKEN in the environment. Unset them or replace with a PAT that has workflow permissions, then retry.
• Quick fix for local shells: GITHUB_TOKEN= gh workflow run "<workflow>" -f key=value (clears the env var for that command).
• In GitHub Actions, prefer GH_TOKEN set to a PAT or GitHub App token when you need to trigger workflows; the default GITHUB_TOKEN can be too limited for dispatching other workflows.

Secrets & variables

• Use gh secret for Actions/Dependabot/Codespaces secrets; use gh variable for Actions/Dependabot variables.
• Scope to repo/org/environment as needed; check gh secret set --help and gh variable set --help for scope flags.
• Prefer stdin or --body to avoid shell history; confirm overwrite and scope with the user.

Releases & tags

• Use gh release list/view/create/download/delete.
• Prefer --generate-notes for release notes when appropriate; confirm tag names and target commits.

Deployments & environments

• For deployment environments, use environment-scoped secrets/variables (-e <env>).
• For deployment history or custom deploy APIs, use gh api with --paginate and --jq as needed.

PRs, issues, and repo admin

• Use gh pr and gh issue for everyday collaboration.
• Use gh repo view/fork/clone/sync for repo operations.
• Keep git operations (branching, rebasing, pushing) explicit and separate from gh steps.

API & advanced

• Use gh api for endpoints not covered by built-in commands.
• Capture JSON with gh api ... --jq or --paginate for large lists.

Troubleshooting auth

• Resource not accessible by integration usually means the CLI is using an integration token (often GITHUB_TOKEN) that cannot dispatch workflows. Prefer a PAT stored via gh auth login --with-token or set GH_TOKEN to a PAT with workflow permissions; avoid leaving GITHUB_TOKEN exported in local shells.
• GH_TOKEN/GITHUB_TOKEN environment variables override stored gh auth. If you see unexpected 403s, unset them or replace with a PAT/GitHub App token that has Actions/workflow permissions before retrying.

Self-improving loop (automated + manual)

Automated (always on when using scripts/ghx):

1. Command outcomes are logged to references/usage-log.jsonl.
2. scripts/auto_improve.py updates references/auto-summary.md and can append repeatable learnings to references/gh-ops-notes.md.

Manual (when new patterns are discovered):

1. Append new command patterns, flags, or pitfalls to references/gh-ops-notes.md.
2. If a command/flag is missing or changed, update references/gh-command-map.md.
3. Run scripts/refresh_gh_reference.sh to refresh references/gh-help.md from the locally installed gh.

Resources

scripts/

• scripts/ghx: wrapper that logs gh command outcomes and triggers auto-summary updates.
• scripts/track_command.sh: logs command outcomes to references/usage-log.jsonl.
• scripts/auto_improve.py: generates references/auto-summary.md and auto-notes.
• scripts/refresh_gh_reference.sh: regenerate references/gh-help.md from local gh help output.

references/

• references/gh-command-map.md: task-to-command map and safe defaults.
• references/gh-help.md: auto-generated help snapshot from the local gh version.
• references/gh-ops-notes.md: living notes for patterns, pitfalls, and team conventions.
• references/auto-summary.md: auto-generated success/failure summary for recent commands.
• references/usage-log.jsonl: append-only command log (redacted).