gh

What it does

How to write it

gh COMMAND SUBCOMMAND [FLAGS]
gh api ENDPOINT [-X METHOD] [-f key=value]

Main parts

Commands

auth login / status

Log in / check the login.

repo clone|create|view|fork

Repositories.

pr create|list|view|checkout|review|merge

Pull requests.

issue create|list|view|close

Issues.

run list|view|watch|rerun

GitHub Actions runs.

workflow list|run|enable|disable

Workflows.

secret set|list|delete

Actions secrets.

variable set|list

Actions variables.

release create|list|download

Releases.

api ENDPOINT

Call the REST or GraphQL API.

attestation verify

Check build provenance of an artifact.

ruleset list|view

Repository rules.

Most used

Nothing matches this filter.

$ run as a normal user# run as root (or with sudo)

1. 1Log in and check

   $gh auth login
   $gh auth status

2. 2Open a pull request from your branch

   $git push -u origin feat/add-health-check
   $gh pr create --title "Add /health endpoint" --body "Adds a health check for the load balancer." --base main
   $gh pr view --web

3. 3Review and check out a colleague's PR

   $gh pr list
   $gh pr checkout 42
   $gh pr diff 42
   $gh pr review 42 --approve -b "Looks good"

4. 4Watch a workflow run and read failed logs

   $gh run list --limit 5
   $gh run watch
   $gh run view --log-failed
   $gh run rerun 9483721055 --failed

5. 5Start a workflow by hand

   $gh workflow run deploy.yml -f environment=staging

6. 6Set a secret for Actions

   $gh secret set AZURE_CLIENT_ID --body "00000000-0000-0000-0000-000000000000"
   $gh secret set KUBECONFIG < ~/.kube/lab.config
   $gh secret list

7. 7Make a release with files

   $gh release create v1.4.0 dist/*.tar.gz --title "Shop 1.4.0" --notes-file CHANGELOG.md

8. 8Call the API

   $gh api repos/s0sta/platform/pulls?state=open --jq '.[].title'
   $gh api repos/s0sta/platform/branches/main/protection
   $gh api --paginate orgs/myorg/repos --jq '.[].full_name'

9. 9Check Dependabot and code-scanning alerts

   $gh api repos/s0sta/platform/dependabot/alerts --jq '.[] | [.security_advisory.severity, .dependency.package.name] | @tsv'
   $gh api repos/s0sta/platform/code-scanning/alerts --jq '.[].rule.id'

10. 10Verify that an artifact was built by your pipeline

    $gh attestation verify shop.tar.gz --owner s0sta

11. 11Use gh inside a workflow

    $cat .github/workflows/label.yml
        steps:
          - run: gh pr edit ${{ github.event.number }} --add-label "needs-review"
            env:
              GH_TOKEN: ${{ github.token }}

Nothing matches this filter.

Files

~/.config/gh/hosts.yml

Login data.

~/.config/gh/config.yml

Settings and aliases.

Exit codes