Check if a rocm-systems Commit is in a TheRock Nightly Build

Answers the question "Is my rocm-systems commit XYZ included in TheRock build X?" by resolving the build to its rocm-systems pin_sha and asking GitHub whether the user's commit is an ancestor of that pin.

When to Use

Use this skill when:

• User asks "is commit <sha> in TheRock build <X>?"
• User wants to know whether a recent fix has shipped in a nightly
• User shares both a nightly URL/run-id and a commit hash
• Another skill needs a yes/no answer about commit inclusion (not just the pin_sha)

Unless the user says otherwise, this skill targets the rocm-systems repository (ROCm/rocm-systems).

Run URLs for current nightlies are on ROCm/rockrel; legacy pre-June-2026 runs are on ROCm/TheRock. See therock-build-to-commit for manifest and packages URL patterns.

Inputs

Prerequisites

• gh CLI installed and authenticated against github.com (see git-gh-client skill for setup).
• Network access to github.com for the compare API.
• The user's commit must exist on ROCm/rocm-systems (not only in a private fork).

Verify quickly:

gh auth status
gh api repos/ROCm/rocm-systems/commits/<COMMIT_SHA> --jq '.sha' >/dev/null && echo "commit visible"

Process

Phase 1: Resolve the Build to a pin_sha

Invoke therock-build-to-commit with the user's build URL/run-id (and any platform overrides). Capture the reported pin_sha.

Do not re-implement the manifest fetch here - delegate to keep behavior consistent.

# Pseudocode: capture pin_sha emitted by therock-build-to-commit
PIN_SHA=<from therock-build-to-commit>

If therock-build-to-commit fails to produce a pin_sha, surface its error verbatim and stop. Do not guess.

Phase 2: Ancestry Check via GitHub Compare

Ask GitHub whether COMMIT_SHA is an ancestor of PIN_SHA by comparing them:

COMMIT_SHA="$1"
STATUS=$(gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" --jq '.status')

Interpret .status:

The gh api ... compare call also returns counts that are useful to surface:

gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" \
  --jq '{status, ahead_by, behind_by, total_commits}'

Phase 3: Report

Report back in this exact shape:

Commit:           <COMMIT_SHA>
Build:            <RUN_ID>  (pin_sha=<PIN_SHA>)
Status:           <STATUS>   (ahead_by=<N>, behind_by=<M>)
Verdict:          <Included | Not included>
Reason:           <one-line explanation derived from Status row above>
Compare URL:      https://github.com/ROCm/rocm-systems/compare/<COMMIT_SHA>...<PIN_SHA>
Build snapshot:   https://github.com/ROCm/rocm-systems/tree/<PIN_SHA>

Examples

Example 1: Included (commit is an ancestor of pin)

COMMIT_SHA=abc1234abc1234abc1234abc1234abc1234abcd
RUN_ID=22561649510
PIN_SHA=$(./therock-build-to-commit "$RUN_ID")     # via the helper skill
gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" --jq '.status'
# -> "ahead"
# Verdict: Included

Example 2: Exact match

COMMIT_SHA=c7da590396ceef1afaaa1b971f3b3d7d6e3562a9
PIN_SHA=c7da590396ceef1afaaa1b971f3b3d7d6e3562a9
gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" --jq '.status'
# -> "identical"
# Verdict: Included (this commit IS the build's pin)

Example 3: Not included (commit landed after the build)

COMMIT_SHA=deadbeefdeadbeefdeadbeefdeadbeefdeadbeef
RUN_ID=22561649510
PIN_SHA=$(./therock-build-to-commit "$RUN_ID")
gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" --jq '.status'
# -> "behind"
# Verdict: Not included (the commit is newer than pin_sha; wait for the next nightly that pins past it)

Example 4: Diverged (commit lives on a branch the pin never reached)

gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" --jq '.status'
# -> "diverged"
# Verdict: Not included (commit is on a side branch never merged before pin_sha)

Output

This skill produces:

• A clear yes/no verdict on inclusion
• The pin_sha for the build, the GitHub compare status, and ahead_by/behind_by counts
• Links to the GitHub compare view and the repo snapshot at pin_sha

No files are written.

Common Mistakes

Troubleshooting

gh: HTTP 404: Not Found from the compare endpoint

Cause: at least one of COMMIT_SHA or PIN_SHA is not visible on ROCm/rocm-systems.

Steps:

1. Verify each SHA individually:

   gh api repos/ROCm/rocm-systems/commits/<SHA> --jq '.sha'

2. If COMMIT_SHA is missing, ask the user where it lives (fork? unmerged branch?).
3. If PIN_SHA is missing, the manifest may be stale or referencing an unreachable commit - report this to the user; do not guess inclusion.

STATUS is null or unexpected

GitHub occasionally returns extra states for very large diffs. Fall back to inspecting ahead_by and behind_by directly:

gh api "repos/ROCm/rocm-systems/compare/${COMMIT_SHA}...${PIN_SHA}" \
  --jq '{status, ahead_by, behind_by}'

If behind_by == 0, the commit is an ancestor (included). If behind_by > 0 and ahead_by == 0, it's strictly newer than the pin (not included).

gh api returns auth errors

Run gh auth login (see the git-gh-client skill for the full flow). The compare endpoint is public for public repos but gh still requires auth to make requests.

Integration with Other Skills

Notes

• The compare API is the simplest reliable ancestry check that does not require a local clone of rocm-systems. If a local clone is available, git merge-base --is-ancestor <commit> <pin_sha> is an offline equivalent (exit code 0 -> included).
• Source of this recipe: Wiki - Helpful Links and Information, TheRock Nightly Builds section.