Riferimento tecnico completo di GitHub CLI gh

Sintesi esecutiva

gh è la CLI ufficiale open source di GitHub per operare su repository, issue, pull request, Actions, Projects, releases, gists, codespaces, secrets e API direttamente dal terminale. Alla data di questo report, l’ultima release ufficiale rilevata è v2.92.0, pubblicata il 28 aprile 2026; la documentazione primaria è distribuita fra il portale GitHub Docs, il manuale CLI e le release notes del repository cli/cli.

Dal punto di vista operativo, gh è oggi più di un wrapper per pull request e issue: espone un modello coerente a gruppi di comandi (repo, issue, pr, run, workflow, release, project, codespace, search, secret, api, extension) e supporta in molti punti output strutturato JSON, filtri --jq, templating Go, paginazione e cache HTTP, rendendolo adatto sia all’uso interattivo sia all’automazione CI/CD.

I punti pratici più importanti, se si deve standardizzare gh in un team, sono questi: usare pacchetti ufficiali o release binaries; preferire GH_TOKEN per automazione headless; configurare il protocollo Git e, se serve, gh auth setup-git; usare --json e --jq invece del parsing testuale; conoscere la distinzione fra gh workflow per definire/eseguire workflow e gh run per osservare e governare le esecuzioni; trattare le estensioni come codice eseguibile di terze parti, da installare con policy di trust e version pinning.

Due note di progettazione sono particolarmente rilevanti. La prima: non esiste, nelle fonti ufficiali correnti, un gruppo top-level gh milestone; le milestone si gestiscono tramite flag nei comandi gh issue e gh pr, oppure via gh api contro gli endpoint REST delle milestones. La seconda: per Projects, i permessi e gli scope restano un tema esplicito; la documentazione richiede il permesso project per modifiche e indica read:project come alternativa per scenari di sola lettura.

Installazione e avvio rapido

Le fonti ufficiali che ho consolidato distinguono nettamente fra installazioni raccomandate e supportate ufficialmente e pacchetti community/unofficial. Per Linux, GitHub pubblica repository e metadati firmati PGP; per Windows, il canale ufficiale raccomandato è WinGet; per macOS, nella documentazione raccolta il percorso ufficiale ricorrente è Homebrew, oltre ai binaries/precompiled assets pubblicati nelle release. Le build da sorgente richiedono Go 1.26 o superiore.

Piattaforma / metodo	Stato nelle fonti raccolte	Installazione	Aggiornamento	Note tecniche
macOS + Homebrew	ufficiale/raccomandato	brew install gh	brew upgrade gh	Metodo ufficiale anche su Linux; semplice da gestire in ambienti developer.
Linux Debian/Ubuntu/derivati	ufficiale/raccomandato	repository cli.github.com/packages + apt install gh	apt update && apt install gh	Keyring e repo ufficiali; GitHub pubblica fingerprint PGP per verifica.
Linux RPM DNF5	ufficiale/raccomandato	dnf config-manager addrepo ... && dnf install gh --repo gh-cli	dnf update gh	Distinguere DNF5 da DNF4.
Linux RPM DNF4	ufficiale/raccomandato	dnf config-manager --add-repo ... && dnf install gh --repo gh-cli	dnf update gh	Sintassi diversa da DNF5.
Linux yum	ufficiale/raccomandato	yum-config-manager --add-repo ... && yum install gh	yum update gh	Documentato per Amazon Linux 2.
Windows WinGet	ufficiale/raccomandato	winget install --id GitHub.cli	winget upgrade --id GitHub.cli	Serve nuova finestra di Windows Terminal per il refresh di PATH.
Manual binaries / release assets	ufficiale	download dalle release	nuova release	Linux: binaries precompilati per 386, amd64, arm64, armv6; Windows: exe/msi per 386, amd64, arm64; il repository espone inoltre release binaries per più OS.
Build da sorgente	ufficiale	make install	rebuild/manuale	Richiede Go ≥ 1.26; in caso di GOPATH non definito installa in bin/ locale.

Tabella derivata dai documenti ufficiali di installazione Linux/Windows, README del repository e note di build dal sorgente.

Per un bootstrap minimale e ripetibile:

# macOS / Linux con Homebrew
brew install gh

# Debian / Ubuntu ufficiale
(type -p wget >/dev/null || (sudo apt update && sudo apt install wget -y)) \
  && sudo mkdir -p -m 755 /etc/apt/keyrings \
  && out=$(mktemp) && wget -nv -O$out https://cli.github.com/packages/githubcli-archive-keyring.gpg \
  && cat $out | sudo tee /etc/apt/keyrings/githubcli-archive-keyring.gpg > /dev/null \
  && sudo chmod go+r /etc/apt/keyrings/githubcli-archive-keyring.gpg \
  && sudo mkdir -p -m 755 /etc/apt/sources.list.d \
  && echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null \
  && sudo apt update \
  && sudo apt install gh -y

# Windows
winget install --id GitHub.cli

Le istruzioni sopra sono fedeli ai canali ufficiali raccolti; per Linux è raccomandata anche la verifica delle fingerprint PGP prima dell’installazione.

Un caveat importante lato packaging: le fonti ufficiali avvertono che, a novembre 2025, i pacchetti Debian community 2.45.x / 2.46.x risultavano problematici a causa di API GitHub deprecate; perciò, in produzione conviene standardizzare i repository ufficiali GitHub CLI invece dei pacchetti distro non mantenuti dal team gh.

Autenticazione, account e configurazione

Il comando centrale è gh auth login. Il flusso di default è web-based OAuth/device/browser, con salvataggio del token nel credential store di sistema; se lo store non è disponibile, gh può ripiegare su file testo in chiaro. In modalità non interattiva è possibile leggere un token da stdin con --with-token, ma la documentazione raccomanda di preferire GH_TOKEN per l’uso con fine-grained tokens e per l’automazione headless. Per --with-token, il minimo richiesto per PAT classic è repo, read:org e gist. Se il protocollo Git è impostato a ssh, gh rileva o genera una chiave SSH e può proporne l’upload, eventualmente saltabile con --skip-ssh-key.

I comandi di stato e switching sono altrettanto importanti in ambienti enterprise o multi-account: gh auth status verifica stato e host conosciuti, può emettere JSON e ritorna exit code 1 se rileva problemi di autenticazione; gh auth switch cambia l’account attivo per host; gh auth token stampa il token dell’account/host selezionato; gh auth setup-git configura GitHub CLI come credential helper Git per tutti gli host autenticati o per uno specifico host. Per account multipli, GitHub Docs conferma che gh può usare più piattaforme e più account sulla stessa piattaforma, con default su github.com quando il contesto locale non basta a inferire l’host.

Dal punto di vista della configurazione, il gruppo gh config espone clear-cache, get, list, set; get/list/set supportano anche il contesto per-host tramite --host. Le chiavi che emergono esplicitamente nelle fonti raccolte sono almeno: git_protocol (richiamata nel comportamento di gh repo clone), browser (documentata nelle note di v2.0.0), prompt disabilitabile (prompt disabled, introdotto in v1.0.0) e pager. Non ho trovato, nelle fonti raccolte, un unico elenco ufficiale sintetico di tutte le config keys operative in una sola pagina del manuale; dove un dettaglio non era esplicitato, lo segnalo come non interamente specificato in questo report.

Per Projects, c’è una differenza importante rispetto ai workflow standard. Il gruppo gh project dichiara come scope minimo project, e la documentazione API/CLI collegata precisa che per accessi read-only si può usare read:project; per aggiungere issue o PR ai progetti, anche gh issue create, gh issue edit, gh pr create e gh pr edit richiedono esplicitamente autorizzazione adeguata.

Esempi pratici di autenticazione e setup:

# login browser-based
gh auth login --web --clipboard

# login non interattivo da file
gh auth login --with-token < mytoken.txt

# impostare gh come credential helper Git
gh auth setup-git

# controllare lo stato auth in JSON
gh auth status --json hosts

# cambiare account attivo per host enterprise
gh auth switch --hostname enterprise.internal --user monalisa

Gli esempi sono allineati al manuale ufficiale di auth login/status/switch/setup-git.

Sintassi, ambiente di esecuzione e riferimento comandi

La grammatica di gh è coerente e gerarchica:

gh <gruppo> <sottocomando> [argomenti] [flag]
gh api <endpoint> [flags]
gh auth <subcommand> ...
gh repo <subcommand> ...
gh pr <subcommand> ...
gh workflow <subcommand> ...
gh run <subcommand> ...

Il manuale top-level documenta i gruppi core (auth, codespace, gist, issue, pr, project, release, repo) e i gruppi aggiuntivi (alias, api, config, extension, label, search, secret, ssh-key, workflow, run, ecc.). A livello strettamente top-level, l’opzione documentata è --version; il pattern -R/--repo, --json, --jq, --template, --web è invece ricorrente ma non universalmente globale, cioè dipende dal gruppo/sottocomando.

Le variabili d’ambiente più importanti, consolidate da gh help environment, sono queste:

Categoria	Variabili chiave	Uso tecnico
Autenticazione	GH_TOKEN, GITHUB_TOKEN, GH_ENTERPRISE_TOKEN, GITHUB_ENTERPRISE_TOKEN	Token per github.com/ghe.com o GHES; hanno precedenza sulle credenziali memorizzate.
Targeting	GH_HOST, GH_REPO	Forzano host e repository quando il contesto locale non basta.
UX / editor / browser	GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR, GH_BROWSER, BROWSER, GH_PAGER, PAGER	Controllano editor, browser e pager.
Debug	GH_DEBUG, DEBUG	Verbose logging; GH_DEBUG=api logga anche traffico HTTP.
Rendering terminale	NO_COLOR, CLICOLOR, CLICOLOR_FORCE, GH_COLOR_LABELS, GH_FORCE_TTY, GH_MDWIDTH	Gestiscono colore, layout TTY e rendering Markdown.
Update / config / prompt	GH_NO_UPDATE_NOTIFIER, GH_NO_EXTENSION_UPDATE_NOTIFIER, GH_CONFIG_DIR, GH_PROMPT_DISABLED, GH_PATH	Controllano notifiche aggiornamento, config dir e prompt interattivi.
Accessibilità / telemetria	GH_ACCESSIBLE_COLORS, GH_ACCESSIBLE_PROMPTER, GH_TELEMETRY, DO_NOT_TRACK, GH_SPINNER_DISABLED	Accessibilità, telemetria, spinner.

Questa tabella è una riduzione ragionata della pagina ufficiale gh help environment; la lista completa nelle fonti raccolte è più ampia ma coerente con le categorie mostrate.

Gli exit code documentati a livello help topic sono: 0 nessun errore, 1 comando fallito, 2 comando cancellato, 4 autenticazione richiesta. La stessa documentazione avverte che alcuni sottocomandi possono definire codici aggiuntivi. Un caso concreto: gh auth status in output testuale esce con 1 se rileva account con problemi, mentre con --json ritorna 0 salvo errori fatali.

La tabella seguente consolida il riferimento comandi richiesto dall’utente. Dove possibile ho indicato i flag ricorrenti più utili; l’elenco esaustivo dei flag resta per sottocomando nel manuale ufficiale aggregato gh help reference.

Gruppo	Sottocomandi / capacità principali	Flag ricorrenti ad alto valore	Esempio
gh auth	login, logout, refresh, setup-git, status, switch, token	--web, --with-token, --hostname, --git-protocol, --show-token, --json	gh auth status --json hosts
gh repo	create, clone, list, view, fork, sync, edit, rename, delete, deploy-key, autolink	--public/--private/--internal, --clone, --source, --push, -R, --json	gh repo create my-org/app --private --clone
gh issue	create, list, status, view, edit, comment, close, reopen, transfer, develop	-R, --json, --jq, --search, --state, --label, --milestone, --project	gh issue create --title "Bug" --label bug
gh pr	create, list, status, view, checkout, diff, review, merge, ready, update-branch, edit, checks, revert	-R, --json, --jq, --fill, --draft, --label, --milestone, --project, --reviewer	gh pr create --fill --draft
gh gist	create, list, view, edit, clone, rename, delete	--desc, --public, --filename, --raw, --files	gh gist create notes.md --desc "memo" --public
gh api	REST v3 e GraphQL v4	--method, --field, --raw-field, --input, --paginate, --cache, --jq, --template, --preview	gh api repos/{owner}/{repo}/releases --paginate
gh alias	set, list, import, delete	--shell, --clobber	gh alias set co "pr checkout"
gh extension	browse, create, exec, install, list, remove, search, upgrade	--precompiled, --pin, --force, --all, --dry-run	gh extension install owner/gh-tool --pin v1.2.0
gh workflow	list, view, run, enable, disable	-R, --json, --ref, --field, --raw-field	gh workflow run ci.yml -r main -f env=prod
gh run	list, view, watch, rerun, download, cancel, delete	-R, --json, --event, --status, --workflow, --log, --log-failed, --exit-status	gh run watch 123456 --exit-status
gh release	create, edit, list, view, upload, download, delete, delete-asset, verify, verify-asset	--draft, --generate-notes, --notes-file, --prerelease, --latest, --verify-tag, --clobber, --json	gh release create v1.2.0 --generate-notes --draft
gh codespace	create, list, view, ssh, logs, ports, rebuild, stop, delete, code, cp, jupyter	--repo, --branch, --machine, --location, --idle-timeout, --retention-period, --json	gh codespace create -R org/repo -b main -m basicLinux32gb
gh secret	set, list, delete su repo, org, env, user	--app, --env, --org, --user, --repos, --visibility, --env-file, --no-store	gh secret set API_KEY -b "$API_KEY"
gh ssh-key	add, list, delete	--title, --type	gh ssh-key add ~/.ssh/id_ed25519.pub --title laptop
gh search	code, commits, issues, prs, repos	--json, --jq, --limit, --owner, --repo, --web, filtri per dominio di ricerca	gh search repos "platform engineering" --owner my-org
gh label	create, list, edit, delete, clone	-R, --color, --description, --force, --json, --search	gh label create "needs-triage" --color FF0000
gh project	create, list, view, edit, field-*, item-*, link, unlink, copy, mark-template, close, delete	--owner, --format json, --jq, --template, --web	gh project item-list 1 --owner cli
milestone	nessun gruppo dedicato nelle fonti ufficiali correnti	usare --milestone in issue/pr oppure gh api sugli endpoint REST /milestones	gh issue list --milestone "v1.0"

Sul fronte Actions, il manuale top-level classifica gh workflow, gh run e gh cache come famiglie specifiche. Nel perimetro richiesto dall’utente, workflow e run coprono la quasi totalità dei casi operativi: dispatch, visualizzazione, log, watch, rerun e governance dei run.

Workflow operativi guidati

Il ciclo operativo più comune con gh unisce provisioning repository, issue/branch, PR, review, CI e release. I sottocomandi coinvolti sono ben supportati dal manuale e dai tutorial ufficiali GitHub Docs.

flowchart LR
    A[gh repo create] --> B[git clone or gh repo clone]
    B --> C[git checkout -b feature/x]
    C --> D[git push origin feature/x]
    D --> E[gh pr create]
    E --> F[gh pr review]
    F --> G[gh run watch]
    G --> H[gh pr merge]
    H --> I[gh release create]

Repository bootstrap. Per creare un repository remoto in modo non interattivo, clonarlo e partire da una working copy locale:

gh repo create my-org/payments-api \
  --private \
  --clone \
  --description "Payments service" \
  --add-readme \
  --gitignore Go \
  --license mit

cd payments-api
gh repo view --web

gh repo create supporta anche il bootstrap da directory locale con --source e il push di commit esistenti con --push; gh repo clone eredita il protocollo Git configurato e, se cloni un fork, può aggiungere upstream automaticamente.

Issue-driven branching e pull request. Un pattern estremamente utile è far partire il lavoro da issue, poi creare la PR con metadati completi:

gh issue create \
  --title "Gestire timeout lato gateway" \
  --body "Timeout configurabile per PSP" \
  --label enhancement \
  --milestone "Q2"

gh issue develop 123 --checkout --name feature/123-gateway-timeout

# ... sviluppo locale ...
git push -u origin feature/123-gateway-timeout

gh pr create \
  --fill \
  --draft \
  --label enhancement \
  --milestone "Q2" \
  --reviewer my-org/backend-team

gh issue develop collega branch e issue; gh pr create può derivare titolo/body dai commit con --fill, aprire draft PR, associare label, reviewers, milestone e project. GitHub Docs conferma anche che --base, --head, --title, --body, --draft, --label, --milestone e --project sono i principali strumenti di composizione della PR da CLI.

Review, checks e merge. Una volta aperta la PR, il ciclo di review e merge è lineare:

gh pr view 456 --comments
gh pr review 456 --comment -b "LGTM, ma aggiorna i test di integrazione"
gh pr review 456 --approve

gh run list --workflow ci.yml --limit 5
gh run watch 987654321 --exit-status

gh pr merge 456 --squash --delete-branch --auto

gh pr review supporta --approve, --comment e --request-changes; gh run watch --exit-status è utile in shell script e pipeline locali; gh pr merge supporta strategie --merge, --rebase, --squash, auto-merge e, sui branch con merge queue, un comportamento specifico in cui la PR può essere accodata invece di essere mergiata immediatamente.

Dispatch e osservabilità di workflow GitHub Actions. Per lanciare manualmente un workflow workflow_dispatch, osservarne l’esecuzione e recuperare log/artifacts:

gh workflow run deploy.yml -r main -f environment=staging
gh run list --workflow deploy.yml --limit 1
gh run view 987654321 --log-failed
gh run download 987654321 -D ./artifacts

Da v2.87.0, gh workflow run stampa immediatamente l’URL del run creato, riducendo il tempo di feedback. La famiglia gh run completa il dispatch con visibilità su stato, log, artifacts, retry e cancellazione.

Release, draft e changelog. La pipeline di rilascio supporta draft, prerelease, note generate e verifica di integrità:

git tag v1.4.0
git push origin v1.4.0

gh release create v1.4.0 \
  --draft \
  --generate-notes \
  --latest \
  dist/*.tar.gz dist/*.zip

gh release view v1.4.0
gh release upload v1.4.0 ./sbom.json
gh release verify v1.4.0

Il comando gh release create supporta --generate-notes via Release Notes API, --notes-file, --notes-from-tag, --prerelease, --latest, --discussion-category e --verify-tag; GitHub Docs conferma che le release notes generate automaticamente includono overview dei cambiamenti, PR mergeate, contributor e link al changelog completo.

flowchart TD
    A[git tag vX.Y.Z] --> B[gh release create --draft]
    B --> C[--generate-notes or --notes-file]
    C --> D[gh release upload assets]
    D --> E[gh release verify]
    E --> F[Publish / mark latest]

Automazione, JSON, API ed estensioni

Per l’automazione, le due regole pratiche da seguire sono: evitare prompt e lavorare su output strutturati. Le fonti ufficiali raccomandano infatti di passare esplicitamente titolo/body/flag per i comandi che altrimenti aprirebbero prompt, mentre il topic gh help formatting spiega che molti comandi espongono --json, --jq e --template. Inoltre, il filtraggio --jq è incorporato nella CLI: non occorre installare l’utility jq di sistema per usarlo in gh.

Esempi robusti di scripting non interattivo:

# headless auth
export GH_TOKEN="$MY_FINE_GRAINED_TOKEN"

# ottenere campi disponibili per un comando
gh pr list --json

# selezionare PR mergeabili
gh pr list \
  --json number,title,mergeStateStatus \
  --jq '.[] | select(.mergeStateStatus=="CLEAN") | {number, title}'

# elencare issue aperte con label critiche
gh issue list \
  --json number,title,labels \
  --jq 'map(select(any(.labels[]?; .name=="critical")))'

# richiesta API paginata con cache locale
gh api repos/{owner}/{repo}/issues \
  --paginate \
  --cache 1h \
  --jq '.[].title'

Questi pattern sono direttamente supportati dalla documentazione ufficiale di gh help formatting e gh api: campi JSON enumerabili, query jq, template Go, requests REST/GraphQL, field typing, body input, paginazione e caching.

Quando vuoi formattare output per dashboard CLI o report rapidi, il supporto template è sorprendentemente potente. Le funzioni documentate includono tablerow, tablerender, timeago, timefmt, truncate, hyperlink, oltre ad alcune funzioni Sprig come contains, hasPrefix, hasSuffix, regexMatch. Questo rende gh un tool adatto anche a wrapper shell e operator tooling senza passare per parser esterni complessi.

Un pattern molto utile nei workflow GitHub Actions è usare GH_TOKEN come credenziale implicita del job. La documentazione ufficiale mostra sia, lato auth login, l’uso di GH_TOKEN: ${{ github.token }} in automazione, sia, lato GitHub Actions docs, la possibilità di eseguire qualunque comando gh nei workflow.

name: comment-on-issue
on:
  issues:
    types: [opened]

jobs:
  comment:
    runs-on: ubuntu-latest
    permissions:
      issues: write
    env:
      GH_TOKEN: ${{ github.token }}
    steps:
      - run: gh issue comment ${{ github.event.issue.number }} --body "Ticket ricevuto."

Il sistema delle estensioni è una delle differenze architetturali più importanti introdotte nella linea 2.x. gh extension supporta browse, create, exec, install, list, remove, search, upgrade; le repository delle estensioni devono iniziare con prefisso gh-. Per installazione remota, gh prova prima a usare release artifacts se disponibili; in assenza di release, clona la repository assumendo una script extension. --pin consente il pinning a tag o commit.

Per creare un’estensione:

# script-based
gh extension create foobar

# precompiled in Go
gh extension create --precompiled=go foobar

# test locale
cd gh-foobar
gh extension install .
gh foobar

Per pubblicare un’estensione è importante essere precisi: non esiste un sottocomando gh extension publish nelle fonti ufficiali raccolte. La pubblicazione avviene creando una repository gh-<name> e, nel caso di estensioni precompilate, pubblicando una release con asset binari nominati secondo la convenzione gh-<name>-<os>-<arch>[.exe]. Per le interpreted extensions, basta normalmente rendere pubblica la repository col file eseguibile in root; per le precompiled, il flusso ufficiale usa gh repo create, tagging Git e gh release create.

Esempio di pubblicazione precompilata:

git init -b main
git add .
git commit -m "Initial commit"
gh repo create gh-whoami --source=. --public --push

git tag v1.0.0
git push origin v1.0.0

GOOS=windows GOARCH=amd64 go build -o gh-whoami-windows-amd64.exe
GOOS=linux   GOARCH=amd64 go build -o gh-whoami-linux-amd64
GOOS=darwin  GOARCH=amd64 go build -o gh-whoami-darwin-amd64

gh release create v1.0.0 ./*amd64*

Per migliorare discoverability, la docs raccomanda di aggiungere il topic repository gh-extension; come ausilio al rilascio cross-platform, segnala anche l’action gh-extension-precompile.

Troubleshooting, sicurezza, prestazioni, versioni e risorse

Le FAQ operative più frequenti hanno tutte risposte abbastanza chiare nelle fonti ufficiali:

sudo apt install gh fallisce con “Unable to locate package gh”. In pratica stai quasi sempre usando i repository distro sbagliati o non hai configurato il repository GitHub CLI ufficiale. Le istruzioni ufficiali Debian/Ubuntu richiedono keyring e source list cli.github.com/packages; inoltre esiste un issue storico in cui il problema si manifesta esattamente così.

gh auth login è inaffidabile su WSL/VM. La release 2.87.0 ha corretto casi rari di drift fra wall clock e monotonic clock che rompevano il polling OAuth in WSL o VM. Se il problema persiste, il primo passo è aggiornare gh; se sei su 2.87.1, le release notes ufficiali dicono esplicitamente di saltarla e aggiornare a 2.87.2, perché 2.87.1 è stata una release incompleta.

I prompt interattivi non funzionano bene in Git Bash / MinTTY su Windows. La pagina ufficiale gh mintty consiglia tre workaround: reinstallare Git for Windows con pseudo console sperimentali, usare un terminale diverso come Windows Terminal, oppure prefissare il comando con winpty sapendo che possono esserci glitch UI.

Uso più account o più piattaforme e gh punta all’host sbagliato. La docs ufficiale conferma che gh usa il contesto del repository locale quando disponibile; in assenza di contesto, defaulta a github.com. Le correzioni operative sono GH_HOST, --hostname, gh auth switch e, quando lavori fuori da una working tree, GH_REPO.

gh project o --project danno errori di autorizzazione. È normale quando il token non ha gli scope necessari. La docs di gh project e dei comandi issue/pr che agganciano project richiede autorizzazione esplicita; per lettura si può usare read:project, per modifica project.

Le query gh search con qualificatori negativi rompono la shell. È un caso documentato ufficialmente: su Unix-like devi usare --, su PowerShell --% seguito da --, altrimenti un filtro come -label:bug viene interpretato come flag CLI invece che parte della query.

Dal lato sicurezza, le best practice motivate dalle fonti sono abbastanza nette. In installazione Linux, verifica fingerprint PGP e checksum forti del keyring; evita MD5 salvo ambienti legacy. In autenticazione, preferisci credential store e GH_TOKEN per headless/fine-grained token, evitando di stampare token in chiaro con gh auth status --show-token o gh auth token dentro log CI. Per release e supply chain, gh release verify e gh release verify-asset aiutano a validare che un asset provenga realmente da una release. Per estensioni, tratta repository e release asset come codice eseguibile di terze parti: pinna versioni con --pin, mantieni allowlist e revisiona il codice prima dell’uso in ambienti sensibili.

Dal lato prestazioni, i miglioramenti più concreti documentati recentemente sono in 2.87.0 e 2.89.0: reviewer/assignee selection basata su ricerca invece del preload massivo, immediate workflow run URL, riduzione delle richieste superflue in gh issue create e gh issue transfer, e nuovo prompter sperimentale. Sul piano pratico, per script rapidi conviene usare gh api --cache, --paginate solo quando necessario, e disabilitare gli update notifier in ambienti non interattivi con GH_NO_UPDATE_NOTIFIER / GH_NO_EXTENSION_UPDATE_NOTIFIER.

Per la migrazione tra versioni, le fonti non offrono una matrice unica e centrale “major version compatibility matrix”; la ricostruzione più affidabile passa dalle release notes ufficiali. Il quadro sintetico è questo: v1.0.0 ha reso stabile la CLI e introdotto, fra le altre cose, gh release, gh pr checks, i comandi gist principali, gh auth login --web, il topic gh help environment, il pager support e il setting prompt disabled; v2.0.0 ha introdotto il sistema delle estensioni, GH_FORCE_TTY, repo sync, funzioni template per tabel rendering e configurazione browser; la linea 2.87.x–2.89.x ha migliorato affidabilità e performance su workflow/auth/project-ish operations; v2.92.0 è la latest release ufficiale rilevata in questo report. Se stai migrando fleet eterogenee, la vera soglia concettuale è 1.x → 2.x, soprattutto per estensioni, scripting avanzato e gestione release/Actions più matura.

Una lista pratica di estensioni e risorse utili emerse dalle fonti ufficiali: gh user-status, gh branch, gh contribute, gh screensaver, gh triage come esempi/promemoria storici del modello extension; gh es per amministrazione GHES; il topic repository gh-extension per discovery; la docs “Creating GitHub CLI extensions”; la pagina “Using GitHub CLI extensions”; il manuale completo cli.github.com/manual; e il repository cli/cli come fonte primaria per release notes e changelog.

Limiti e punti esplicitamente non specificati nelle fonti consolidate qui: non è emersa una pagina unica che elenchi in forma compatta tutte le config keys di gh; non esiste, nelle fonti correnti riviste, un gruppo gh milestone; e non esiste un comando gh extension publish, perché la pubblicazione delle estensioni passa per repository + release assets, non per un sottocomando dedicato.