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).