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

...

Workflow Run

NOTE: To sneak a run in that is not in the default branch, just temporarily add a:

on:
  push

Trigger workflow run:

gh workflow run [<workflow-id> | <workflow-name>] [flags]

Examples:

# Have gh prompt you for what workflow you'd like to run and interactively collect inputs
$ gh workflow run

# Run the workflow file 'triage.yml' at the remote's default branch
$ gh workflow run triage.yml

# Run the workflow file 'triage.yml' at a specified ref
$ gh workflow run triage.yml --ref my-branch

# Run the workflow file 'triage.yml' with command line inputs
$ gh workflow run triage.yml -f name=scully -f greeting=hello

# Run the workflow file 'triage.yml' with JSON via standard input
$ echo '{"name":"scully", "greeting":"hello"}' | gh workflow run triage.yml --json

NOTE: the INPUTS names do appear to be case sensitive!!

reference: https://cli.github.com/manual/gh_workflow_run

Workflow Run List

To see runs for this workflow, try:

gh run list --workflow=test.yaml

In JSON Format:

gh run list --workflow=test.yaml --json=displayTitle,url,databaseId

Limit to last run:

gh run list --workflow=test.yaml --json=displayTitle,url,databaseId -L 1
gh run list --workflow=test.yaml --json=displayTitle,url,databaseId --limit 1

JSON Fields:

Available fields:
  conclusion
  createdAt
  databaseId
  displayTitle
  event
  headBranch
  headSha
  name
  number
  startedAt
  status
  updatedAt
  url
  workflowDatabaseId
  workflowName

Sample:

[
  {
    "databaseId": 304415075xx,
    "displayTitle": "Test test",
    "url": "https://github.com/myorg/myrepo/actions/runs/304415075xx"
  }
]

COMMAND LIST

Manual:

https://cli.github.com/manual

$ gh --help
Work seamlessly with GitHub from the command line.

USAGE
  gh <command> <subcommand> [flags]

CORE COMMANDS
  auth:        Authenticate gh and git with GitHub
  browse:      Open the repository in the browser
  codespace:   Connect to and manage codespaces
  gist:        Manage gists
  issue:       Manage issues
  org:         Manage organizations
  pr:          Manage pull requests
  release:     Manage releases
  repo:        Manage repositories

GITHUB ACTIONS COMMANDS
  run:         View details about workflow runs
  workflow:    View details about GitHub Actions workflows

ALIAS COMMANDS
  co:          Alias for "pr checkout"

ADDITIONAL COMMANDS
  alias:       Create command shortcuts
  api:         Make an authenticated GitHub API request
  completion:  Generate shell completion scripts
  config:      Manage configuration for gh
  extension:   Manage gh extensions
  gpg-key:     Manage GPG keys
  label:       Manage labels
  search:      Search for repositories, issues, and pull requests
  secret:      Manage GitHub secrets
  ssh-key:     Manage SSH keys
  status:      Print information about relevant issues, pull requests, and notifications across repositories
  variable:    Manage GitHub Actions variables

HELP TOPICS
  actions:     Learn about working with GitHub Actions
  environment: Environment variables that can be used with gh
  exit-codes:  Exit codes used by gh
  formatting:  Formatting options for JSON data exported from gh
  mintty:      Information about using gh with MinTTY
  reference:   A comprehensive reference of all gh commands

FLAGS
  --help      Show help for command
  --version   Show gh version

EXAMPLES
  $ gh issue create
  $ gh repo clone cli/cli
  $ gh pr checkout 321

LEARN MORE
  Use 'gh <command> <subcommand> --help' for more information about a command.
  Read the manual at https://cli.github.com/manual