GitHub/GH Client

Installation

https://github.com/cli/cli/releases/tag/v2.41.0

wget https://github.com/cli/cli/releases/download/v2.41.0/gh_2.41.0_linux_amd64.deb
dpkg -i gh_2.41.0_linux_amd64.deb

Really really old version:

pip3 install gh

winget

See WinGet#GitHub Client

winget install --id GitHub.cli --source winget

Doc

https://cli.github.com/manual/gh_api

Repo List

gh repo list

Clone Repo

https:

gh repo clone [ORG_or_OWNER]/[REPO]
gh repo clone [ORG_or_OWNER]/[REPO]  [folder]
# eg. gh repo clone myorg/myrepo  myrepo

ssh:

gh repo clone git@github.com:[ORG_or_OWNER]/[REPO]

Set protocol to be ssh:

gh config set git_protocol ssh

See current protocol: (https is default)

gh config get git_protocol
 https
 # or
 ssh

Repo Update

"Sync destination repository from source repository. Syncing uses the default branch of the source repository to update the matching branch on the destination repository so they are equal. A fast forward update will be used except when the `--force` flag is specified, then the two branches will be synced using a hard reset."

 # Sync local repository from remote parent
 $ gh repo sync

 # Sync local repository from remote parent on specific branch
 $ gh repo sync --branch v1

 --force           Hard reset the branch of the destination repository to match the source repository

Checkout PR to repo

gh pr checkout [PR#]

Reference: https://cli.github.com/manual/gh_pr_checkout

PR Management

Merge PR

gh pr merge <pr-number>
gh pr merge <pr-number> --delete branch

Closing an Unmerged PR

gh pr close <pr-number>
gh pr close <pr-number> --delete branch

Delete Branch on GitHub

gh api \
 -X DELETE \
 repos/OWNER/REPO/git/refs/heads/BRANCH

reference: https://docs.github.com/en/rest/git/refs?apiVersion=2026-03-10#delete-a-reference

NOTE: Must have "Write" permission on the Contents - Repository contents, commits, branches, downloads, releases, and merges.

Auth

gh auth status

Bad status:

$ gh auth status
github.com
  X Failed to log in to github.com account YOUR-USER (/home/user/.config/gh/hosts.yml)
  - Active account: true
  - The token in /home/user/.config/gh/hosts.yml is invalid.
  - To re-authenticate, run: gh auth login -h github.com
  - To forget about this account, run: gh auth logout -h github.com -u YOUR-USER

Good status:

# gh auth status
github.com
  ✓ Logged in to github.com account YOUR-USER (/home/user/.config/gh/hosts.yml)
  - Active account: true
  - Git operations protocol: ssh
  - Token: ghp_************************************
  - Token scopes: 'admin:public_key', 'read:org', 'repo'

Login

gh auth login -h github.com

# gh auth login -h github.com
? What is your preferred protocol for Git operations on this host? SSH
? Upload your SSH public key to your GitHub account? /root/.ssh/github.pub
? Title for your SSH key: GitHub CLI
? How would you like to authenticate GitHub CLI? Paste an authentication token
Tip: you can generate a Personal Access Token here https://github.com/settings/tokens
The minimum required scopes are 'repo', 'read:org', 'admin:public_key'.
? Paste your authentication token: ****************************************
- gh config set -h github.com git_protocol ssh
✓ Configured git protocol
! Authentication credentials saved in plain text
✓ SSH key already existed on your GitHub account: /root/.ssh/github.pub
✓ Logged in as YOUR-USER-NAME
! You were already logged in to this account

Login with a web browser, grab the one-time code, and visit:

https://github.com/login/device

GH_TOKEN

PRIVATE_KEY='private_key.pem'
APP_ID='12345'
INSTALLATION_ID='54321'

JWT=`./make-jwt.py $PRIVATE_KEY $APP_ID`
GH_TOKEN=`curl -s --request POST --url "https://api.github.com/app/installations/$INSTALLATION_ID/access_tokens" --header "Accept: application/vnd.github+json" --header "Authorization: Bearer $JWT" --header "X-GitHub-Api-Version: 2022-11-28" | python -c "import sys, json; print(json.load(sys.stdin)['token'])"`
echo "export GH_TOKEN=$GH_TOKEN"

See make-jwt.py



Linux:
 printf <YOUR_TOKEN> | gh auth login --with-token

 export PAT="<YOUR_TOKEN>"
 printf "%s" "$PAT" | gh auth login --with-token

Windows Powershell:
 $PAT="<YOUR_TOKEN>"
 $PAT | gh auth login --with-token

Windows CMD:
 set PAT=<YOUR_TOKEN>
 echo %PAT% | gh auth login --with-token



GH_TOKEN:
* Run gh commands: Once the environment variable is set, the gh client will automatically use this token for authentication without needing to run gh auth login

Linux:
 export GH_TOKEN="<YOUR_TOKEN>"

Windows Powershell:
  $env:GH_TOKEN="<YOUR_TOKEN>"

Windows CMD:
 set GH_TOKEN="<YOUR_TOKEN>"

api
 gh api

 ref: https://cli.github.com/manual/gh_api

Action Runners
 https://docs.github.com/en/rest/actions/self-hosted-runners?apiVersion=2022-11-28

List
page 1 (pagination)
 gh api /orgs/ORG/actions/runners

Installation Key
...

keywords