GitHub Workflow Skill

GitHub workflow management using the gh CLI for pull requests, issues, releases, and the GitHub API.

Authentication

gh reads GH_TOKEN (or GITHUB_TOKEN) from the environment — no interactive gh auth login needed. In the Jonggrang sandbox the token is injected automatically when set in global settings (Git tokens). Verify with:

gh auth status        # shows the active account / token source

If GH_TOKEN is unset, every command below fails with an auth error — set it in the dashboard's global settings, then restart the sandbox.

⚠️ Message Escaping — Common Trap

If a title/body/comment contains backticks (`), $, !, or \, NEVER inline them in -t "..." / -b "...". The shell interprets backticks as command substitution and silently mangles the text (e.g. client_name: command not found, identifiers stripped). This causes real failures: malformed PR/issue comments followed by apologetic corrections.

❌ DON'T — inline special chars in a double-quoted flag

# BROKEN: shell executes `client_name` as a command
gh pr comment 100 -b "Use `client_name` and `wor/` here."

✅ DO — write to a file first, then pass via --body-file

Most gh commands that take a body accept --body-file <path> (and -F/--body-file - for stdin). Prefer it over -b:

# MSG = a path you pick (mktemp, scoped tmp, etc.) unique to this invocation
MSG=$(mktemp)
cat > "$MSG" << 'EOF'
Use `client_name` and `wor/` here. The `gh` tool handles this.
EOF
gh pr comment 100 --body-file "$MSG"

The single-quoted 'EOF' delimiter prevents ALL variable/backtick expansion. Triple-backtick code blocks are safe inside <<'EOF' heredocs — only single backticks and $ trigger substitution in an unquoted heredoc.

# BROKEN: unquoted EOF — backticks in body are still interpreted while writing
cat > "$MSG" << EOF
Use `client_name` here.
EOF

Rule of thumb: body contains `, $, !, or \ → write it to a file with << 'EOF' and pass --body-file, always.

Pull Requests

Push the branch first (or pass --head), and be explicit about base/head so gh doesn't pick the wrong remote/fork.

# Create — simple
gh pr create --base main --head feat/my-branch --title "Add feature" --body "Brief description"

# Create — rich body from a file (see escaping above)
gh pr create --base main --head feat/my-branch --title "Add feature" --body-file "$MSG"

# Specify the repo explicitly (outside the repo, or to avoid wrong remote)
gh pr create -R owner/repo --base main --head feat/x --title "…" --body-file "$MSG"

# List / view / check status
gh pr list --state open
gh pr view 123                 # add --json state,mergeable,reviews for machine output
gh pr diff 123
gh pr checks 123               # CI status for the PR

# Review actions
gh pr comment 123 --body-file "$MSG"
gh pr review 123 --approve            # or --request-changes --body-file "$MSG"
gh pr ready 123                       # mark draft → ready

# Merge (choose one strategy; --delete-branch optional)
gh pr merge 123 --merge               # or --squash / --rebase
gh pr merge 123 --squash --delete-branch

gh pr merge waits for required checks if branch protection demands them; add --auto to enable auto-merge when checks pass.

Issues

gh issue create --title "Bug: …" --body-file "$MSG" --label bug --assignee @me
gh issue list --state open --label bug
gh issue view 42
gh issue comment 42 --body-file "$MSG"
gh issue close 42 --comment "fixed in #123"

Releases

gh release create v1.2.0 --title "v1.2.0" --notes-file "$MSG"
gh release create v1.2.0 --generate-notes            # auto changelog from PRs
gh release upload v1.2.0 ./dist/app.tar.gz           # attach assets
gh release list

REST / GraphQL API (escape-safe via -f / -F)

When you need something the porcelain commands don't cover, hit the API. Pass fields with -f key=value (string) or -F key=@file / -F key=value (typed/file), which avoids shell-escaping the body:

# POST a PR review comment with a body read from a file
gh api --method POST "repos/owner/repo/issues/100/comments" -F "body=@$MSG"

# Read JSON and filter with --jq
gh api "repos/owner/repo/pulls/123" --jq '.mergeable_state'

# GraphQL
gh api graphql -f query='query { viewer { login } }'

Tips

• Machine-readable output: add --json <fields> (+ optional --jq) to most read commands instead of scraping text — e.g. gh pr view 1 --json state,mergeStateStatus.
• Repo context: inside a clone, gh infers the repo from the origin remote. Outside one, always pass -R owner/repo.
• Never run gh auth login in automation — rely on GH_TOKEN.
• Don't paste tokens into commands or commit them; they come from the environment.