github

Use the GitHub CLI to inspect repositories, Actions, tags, releases, and pull requests safely.

Downloads: 4 · ID: a2979891888bf37509000000

Published files and instructions

<!-- FILE: github_skill.md -->
# GitHub Skill

Inspect and manage GitHub repositories, tags, releases, GitHub Actions workflows, and pull requests using the GitHub CLI (`gh`).

## Tool discovery on macOS

`gh` may be installed by Homebrew but unavailable to non-interactive API sessions because `/opt/homebrew/bin` is not in `PATH`. Resolve it before use:

```bash
GH="$(command -v gh || true)"
if [ -z "$GH" ] && [ -x /opt/homebrew/bin/gh ]; then GH=/opt/homebrew/bin/gh; fi
if [ -z "$GH" ] && [ -x /usr/local/bin/gh ]; then GH=/usr/local/bin/gh; fi
[ -n "$GH" ] || { echo "gh not found" >&2; exit 1; }
```

Check authentication without exposing tokens:

```bash
"$GH" auth status
```

The user may have multiple accounts or SSO-authorized organizations. Do not modify authentication, switch accounts, or refresh SSO without explicit instruction.

## Repository inspection

Start by collecting local and remote identity:

```bash
git -C REPO status --short --branch
git -C REPO remote -v
"$GH" repo view OWNER/REPO
```

For several local implementations of the same application, inspect them in parallel and compare:

- current branch and dirty files;
- `origin` URL;
- latest commits and tags;
- workflow files under `.github/workflows`;
- version declarations;
- release scripts and build outputs.

## Tags and releases

Verify both the tag object and the release. A GitHub Release can exist even when a workflow or a different tag-triggered job failed.

```bash
"$GH" release list -R OWNER/REPO --limit 20
"$GH" release view TAG -R OWNER/REPO --json tagName,isDraft,isPrerelease,url,assets
"$GH" api repos/OWNER/REPO/git/ref/tags/TAG
"$GH" api repos/OWNER/REPO/branches/main --jq '.commit.sha'
```

Compare the tag's resolved commit with the intended commit. Annotated tags return an object that may point to a commit; lightweight tags point directly to a commit.

Check that expected assets exist and are uploaded, including platform-specific names and sizes.

## Actions diagnosis

List recent workflow runs:

```bash
"$GH" run list -R OWNER/REPO --limit 30
"$GH" run list -R OWNER/REPO --workflow WORKFLOW --limit 20
```

Inspect a run summary and failed steps:

```bash
"$GH" run view RUN_ID -R OWNER/REPO --json status,conclusion,headSha,headBranch,jobs,url
"$GH" api repos/OWNER/REPO/actions/runs/RUN_ID/jobs
"$GH" run view RUN_ID -R OWNER/REPO --log-failed
```

If `--log-failed` reports `log not found`, use the jobs API. This often happens for expired, cancelled, or incomplete logs. Inspect each job's `steps`, `conclusion`, timestamps, and `html_url`.

Pay attention to:

- tag-triggered release runs versus branch CI runs;
- failures after artifact upload;
- jobs that run for approximately the repository or job timeout;
- the last started step and steps never reached;
- version/tag mismatches;
- cache keys shared by parallel jobs;
- build profile and output-directory mismatches;
- macOS, Windows, and Linux asset coverage.

A successful release workflow does not imply that branch CI passed, and a failed CI workflow does not necessarily mean that release assets are invalid.

## Cache review

For Cargo workflows, distinguish dependency caches from build-output caches:

```yaml
~/.cargo/registry
~/.cargo/git
target
```

The first two are dependency downloads and do not add Git repository blobs. `target` can be large and should use job/profile-specific keys when multiple parallel jobs cache it. Check that a cache path matches the build profile (`target/ci`, `target/debug`, or `target/release`).

## macOS application/path diagnostics

When the application is installed as an `.app` in `/Applications`, distinguish source/build paths from runtime paths. Inspect these separately:

```bash
mdfind "kMDItemCFBundleIdentifier == 'BUNDLE.ID'"
ls -la /Applications/AppName.app/Contents
find /Applications/AppName.app/Contents -maxdepth 3 -type f -print
plutil -p /Applications/AppName.app/Contents/Info.plist
```

For executable and resource paths:

```bash
APP=/Applications/AppName.app
"$APP/Contents/MacOS/AppName" --version
otool -L "$APP/Contents/MacOS/AppName"
```

Do not assume the process working directory is the project directory. GUI applications launched by Finder commonly start with a different working directory. Code should derive resources from the bundle executable/resource location, not from the current directory or a developer home path.

For build scripts, prefer an explicit repository root:

```bash
ROOT="$(cd "$(dirname "$0")" && pwd)"
```

For runtime resources on macOS, use the bundle's resource directory and verify the final `.app` contents after packaging. Avoid hardcoded `/Users/...`, relative paths that depend on `cwd`, and paths that work only from a build directory.

## Safe write operations

Read and inspect before modifying. For commits and pushes:

1. Check status and current branch.
2. Review `git diff --check` and the complete diff.
3. Fetch and check divergence before pushing.
4. If remote is ahead, rebase or merge deliberately; never force-push by default.
5. Commit with a focused message.
6. Push the intended branch.
7. Verify the remote commit and resulting workflow run.

Do not delete releases, move tags, force-push, alter authentication, or rerun workflows unless explicitly requested.

## Common commands

```bash
"$GH" repo clone OWNER/REPO
"$GH" pr list -R OWNER/REPO
"$GH" issue list -R OWNER/REPO
"$GH" workflow list -R OWNER/REPO
"$GH" run rerun RUN_ID -R OWNER/REPO
```

Rerunning a workflow is a write operation and requires explicit user approval.

## Reporting

Summarize:

- repository and commit examined;
- tag/release state;
- workflow status and the specific failing step;
- whether the failure affects published artifacts;
- local uncommitted changes;
- recommended fixes and any remaining uncertainty.

Never print authentication tokens, credential files, or sensitive environment variables.

Redaction report

• No redactions reported