GitHub CLI (gh)

Expert guidance for GitHub CLI operations and workflows.

Installation & Setup

Login to GitHub

gh auth login

Check authentication status

gh auth status

Configure git to use gh as credential helper

gh auth setup-git

Pull Requests

Creating PRs

Create PR interactively

gh pr create

Create PR with title and body

gh pr create --title "Add feature" --body "Description"

Create PR to specific branch

gh pr create --base main --head feature-branch

Create draft PR

gh pr create --draft

Create PR from current branch

gh pr create --fill # Uses commit messages

Viewing PRs

List PRs

gh pr list

List my PRs

gh pr list --author @me

View PR details

gh pr view 123

View PR in browser

gh pr view 123 --web

View PR diff

gh pr diff 123

Check PR status

gh pr status

Managing PRs

Checkout PR locally

gh pr checkout 123

Review PR

gh pr review 123 --approve gh pr review 123 --comment --body "Looks good!" gh pr review 123 --request-changes --body "Please fix X"

Merge PR

gh pr merge 123 gh pr merge 123 --squash gh pr merge 123 --rebase gh pr merge 123 --merge

Close PR

gh pr close 123

Reopen PR

gh pr reopen 123

Ready draft PR

gh pr ready 123

PR Checks

View PR checks

gh pr checks 123

Watch PR checks

gh pr checks 123 --watch

Issues

Creating Issues

Create issue interactively

gh issue create

Create issue with title and body

gh issue create --title "Bug report" --body "Description"

Create issue with labels

gh issue create --title "Bug" --label bug,critical

Assign issue

gh issue create --title "Task" --assignee @me

Viewing Issues

List issues

gh issue list

List my issues

gh issue list --assignee @me

List by label

gh issue list --label bug

View issue details

gh issue view 456

View in browser

gh issue view 456 --web

Managing Issues

Close issue

gh issue close 456

Reopen issue

gh issue reopen 456

Edit issue

gh issue edit 456 --title "New title" gh issue edit 456 --add-label bug gh issue edit 456 --add-assignee @user

Comment on issue

gh issue comment 456 --body "Update"

Repository Operations

Repository Info

View repository

gh repo view

View in browser

gh repo view --web

Clone repository

gh repo clone owner/repo

Fork repository

gh repo fork owner/repo

List repositories

gh repo list owner

Repository Management

Create repository

gh repo create my-repo --public gh repo create my-repo --private

Delete repository

gh repo delete owner/repo

Sync fork

gh repo sync owner/repo

Set default repository

gh repo set-default

Workflows & Actions

Viewing Workflows

List workflows

gh workflow list

View workflow runs

gh run list

View specific run

gh run view 789

Watch run

gh run watch 789

View run logs

gh run view 789 --log

Managing Workflows

Trigger workflow

gh workflow run workflow.yml

Cancel run

gh run cancel 789

Rerun workflow

gh run rerun 789

Download artifacts

gh run download 789

Releases

Creating Releases

Create release

gh release create v1.0.0

Create release with notes

gh release create v1.0.0 --notes "Release notes"

Create release with files

gh release create v1.0.0 dist/*.tar.gz

Create draft release

gh release create v1.0.0 --draft

Generate release notes automatically

gh release create v1.0.0 --generate-notes

Managing Releases

List releases

gh release list

View release

gh release view v1.0.0

Download release assets

gh release download v1.0.0

Delete release

gh release delete v1.0.0

Version Management (pki-manager specific)

IMPORTANT: When creating a new release for this project, you MUST bump the version in ALL THREE package.json files:

• package.json (root - authoritative source)

• frontend/package.json

• backend/package.json

Version Bump Types (Semantic Versioning)

Type When to use Example

patch Bug fixes, minor changes 1.2.0 → 1.2.1

minor New features, backwards compatible 1.2.0 → 1.3.0

major Breaking changes 1.2.0 → 2.0.0

Pre-Release Workflow

Before creating a release, you MUST:

• Check current version in root package.json

• Determine bump type based on changes since last release

• Update ALL package.json files with the new version

• Commit version changes with message: chore: bump version to vX.Y.Z

• Create git tag: git tag vX.Y.Z

• Push tag: git push origin vX.Y.Z

• Create GitHub release: gh release create vX.Y.Z --generate-notes

Complete Release Workflow

1. Determine current version

cat package.json | grep '"version"'

Output: "version": "1.2.0"

2. Update versions in all package.json files

For patch bump (1.2.0 → 1.2.1):

NEW_VERSION="1.2.1"

Edit package.json (root)

Edit frontend/package.json

Edit backend/package.json

All three must have the same version!

3. Commit version bump

git add package.json frontend/package.json backend/package.json git commit -m "chore: bump version to v${NEW_VERSION}"

4. Create and push tag

git tag "v${NEW_VERSION}" git push origin main git push origin "v${NEW_VERSION}"

5. Create GitHub release with auto-generated notes

gh release create "v${NEW_VERSION}" --generate-notes

Or with custom notes

gh release create "v${NEW_VERSION}" --notes "## What's Changed

• Feature A
• Bug fix B
• Improvement C"

Version Synchronization Rules

CRITICAL: All three package.json files MUST have matching versions:

File Path Must Match Root

Root package.json

✓ (authoritative)

Frontend frontend/package.json

✓

Backend backend/package.json

✓

Checking Version Consistency

Quick check all versions

echo "Root: $(cat package.json | grep '"version"' | head -1)" echo "Frontend: $(cat frontend/package.json | grep '"version"' | head -1)" echo "Backend: $(cat backend/package.json | grep '"version"' | head -1)"

Release Checklist

Before releasing, verify:

• All tests pass (pnpm test )

• Build succeeds (pnpm build )

• All three package.json versions match

• Changes are committed to main branch

• No uncommitted changes (git status )

• Previous release tag exists for comparison

Gists

Create gist

gh gist create file.txt

Create gist from stdin

echo "content" | gh gist create -

List gists

gh gist list

View gist

gh gist view <gist-id>

Edit gist

gh gist edit <gist-id>

Delete gist

gh gist delete <gist-id>

Advanced Features

Aliases

Create alias

gh alias set pv "pr view" gh alias set bugs "issue list --label bug"

List aliases

gh alias list

Use alias

gh pv 123

API Access

Make API call

gh api repos/:owner/:repo/issues

With JSON data

gh api repos/:owner/:repo/issues -f title="Bug" -f body="Description"

Paginated results

gh api --paginate repos/:owner/:repo/issues

Extensions

List extensions

gh extension list

Install extension

gh extension install owner/gh-extension

Upgrade extensions

gh extension upgrade --all

Common Workflows

Code Review Workflow

List PRs assigned to you

gh pr list --assignee @me

Checkout PR for testing

gh pr checkout 123

Run tests, review code...

Approve PR

gh pr review 123 --approve --body "LGTM!"

Merge PR

gh pr merge 123 --squash

Quick PR Creation

Create feature branch, make changes, commit

git checkout -b feature/new-feature

... make changes ...

git add . git commit -m "Add new feature" git push -u origin feature/new-feature

Create PR from commits

gh pr create --fill

View PR

gh pr view --web

Issue Triage

List open issues

gh issue list

Add labels to issues

gh issue edit 456 --add-label needs-triage gh issue edit 456 --add-label bug

Assign issue

gh issue edit 456 --add-assignee @developer

Configuration

Set default editor

gh config set editor vim

Set default git protocol

gh config set git_protocol ssh

View configuration

gh config list

Set browser

gh config set browser firefox

Tips

• Use --web flag: Open items in browser for detailed view

• Interactive prompts: Most commands work interactively if you omit parameters

• Filters: Use --author , --label , --state to filter lists

• JSON output: Add --json flag for scriptable output

• Template repos: Use gh repo create --template for templates

• Auto-merge: Enable with gh pr merge --auto