Using Gh

Using GitHub CLI

Use this skill when the task involves a GitHub repository and the gh command is the right interface for inspection or automation.

This skill is for GitHub-side operations, not general Git worktree handling. Use using-git alongside it when commits, branches, or selective staging are part of the task.

Core rules

• Prefer non-interactive gh commands.
• Check authentication first before assuming GitHub operations will work.
• Distinguish clearly between:
  • local Git state,
  • pushed branch state,
  • PR state,
  • Actions run state,
  • release state.
• Do not assume a branch push will trigger the intended workflow. Check the workflow triggers and use a PR or tag when required.
• If git push fails because of local credential-helper problems, do not stop there. gh auth may still be valid.

Authentication

Start with:

gh auth status

Do not assume gh authentication and git push authentication are the same credential path in this environment.

Check both independently when push behaviour matters:

gh auth status
git remote -v

Important distinction:

• gh commands use the token and host configuration managed by GitHub CLI.
• Plain git push may use a separate Git credential helper, stored HTTPS credentials, or another transport-specific mechanism.
• A gh token may lack scopes such as workflow even when plain git push succeeds through another credential path.
• Conversely, gh may be fully usable for API inspection even when git push fails because Git cannot update or access its credential store.

When a workflow file under .github/workflows/ is being created or updated, distinguish carefully between:

• whether gh can inspect repository state and Actions runs, and
• whether the credential used by git push is allowed to update workflow files on GitHub.

If GitHub CLI is authenticated but git push fails through a broken credential helper, a one-off push can still be done by injecting the token explicitly:

git -c credential.helper= \
    -c http.https://github.com/.extraheader="AUTHORIZATION: basic $(printf 'x-access-token:%s' "$(gh auth token)" | base64 -w0)" \
    push -u origin <branch>

Use this sparingly and only for the specific push you need.

Pull requests

Create a PR non-interactively:

gh pr create \
  --repo owner/repo \
  --base master \
  --head feature-branch \
  --title "Short title" \
  --body-file /tmp/pr-body.md

Prefer --body-file for any non-trivial PR description so the structure can be reviewed before submission and multiline markdown is not squeezed into a single shell argument.

Recommended PR body structure:

# Summary

Why the change is being made and the high-level result.

# Changes

What was actually done and how related changes fit together.

# Testing

What was tested, including local checks and CI results when available.

When opening a PR, gather and state the tests that were actually run. If local validation was possible, mention it. If a CI workflow was run successfully, include that fact and the run URL when it helps reviewers.

Create the PR as a draft when the work is incomplete, testing is blocked, or known issues remain that would waste reviewer time.

Inspect the PR in machine-readable form:

gh pr view <number> --repo owner/repo --json number,url,headRefName,baseRefName,state

Use a PR when the workflow triggers on pull_request but not on arbitrary branch pushes.

gh pr create may warn about uncommitted local changes. Treat that as a cue to check the worktree, not as proof that PR creation failed.

Actions runs

List recent runs for one workflow:

gh run list --repo owner/repo --workflow build.yml --limit 10

Inspect a run and its jobs:

gh run view <run-id> --repo owner/repo --json status,conclusion,name,workflowName,jobs,url

Watch a run to completion:

gh run watch <run-id> --repo owner/repo --exit-status

Inspect failed logs when something breaks:

gh run view <run-id> --repo owner/repo --log-failed

When reporting CI state, include:

• run id,
• trigger type,
• overall status,
• which jobs passed or failed,
• whether release jobs ran or were skipped.

Releases

Inspect a release:

gh release view <tag> --repo owner/repo

Inspect structured release data:

gh release view <tag> --repo owner/repo --json name,tagName,isDraft,isPrerelease,url,body,assets

Publish or edit a draft release with prepared notes:

gh release edit <tag> \
  --repo owner/repo \
  --title "v0.02" \
  --notes-file /tmp/release-notes.txt \
  --draft=false

After editing or publishing a release, re-read it with gh release view to confirm:

• draft vs published state,
• final tag URL,
• attached asset names,
• release notes content.

Tag workflows

If a workflow publishes releases from tags:

1. Create and inspect the tag locally.
2. Push only the tag.
3. Watch the tag-triggered run.
4. Confirm the release job completed.
5. Confirm the release exists and assets are attached.

Useful commands:

git tag -a v0.02 -m "Release v0.02"
git show --stat --no-patch v0.02
gh run list --repo owner/repo --workflow build.yml --limit 5
gh release view v0.02 --repo owner/repo

Environment-specific notes

Lessons from this environment:

• gh may be authenticated even when Git's configured credential helper is not writable or is otherwise broken.
• Plain git push may still succeed in that situation if Git can read an existing credential and does not need to update the store.
• gh auth setup-git can fail if the global Git config is not writable. Do not assume that means gh is unusable.
• Successful git push does not prove that the gh token has equivalent repository scopes. Treat Git transport credentials and GitHub CLI token scopes as separate facts to verify.
• When a gh-token-based push is rejected for updating workflow files without workflow scope, retrying with the repository's normal git push path may still work if that path uses different credentials.
• The repository being changed may not be the same repository whose workflow or release should be inspected. Check remotes and repository boundaries first.
• A release created by Actions may initially appear under an untagged draft URL before the final published tag URL is visible. Re-check after the workflow completes.
• When watching a matrix workflow, inspect job names individually so you can tell which profile or variant passed.

When to use this skill

Use this skill for tasks such as:

• checking whether gh authentication is available,
• creating or inspecting pull requests,
• watching GitHub Actions runs,
• fetching failed CI logs,
• checking whether release artifacts exist,
• publishing or editing releases after CI succeeds,
• working around GitHub push credential issues when gh auth is already valid.