TheRock/docs/development/manifest_diff.md

Manifest Diff Report

The manifest diff report is a CI tool that summarizes which TheRock submodule SHAs changed between two commits. It runs automatically on every multi-arch CI run for pull_request and push events, and can also be invoked on demand via direct workflow_dispatch of manifest-diff.yml or locally on the command line.

Summary

TheRock is a CMake super-project pinned to a small set of top-level git submodules (.gitmodules), two of which (rocm-libraries, rocm-systems) are themselves superrepos containing further ROCm components under projects/ and shared/. When a change in TheRock or in any of those upstream repos lands, it can be non-obvious which pointer(s) actually moved. The manifest diff report answers that question: for two TheRock commits (a start and an end), it walks the manifest produced by generate_therock_manifest.py — top-level submodules plus superrepo components — and produces an HTML page listing the new commit range on each one, with links back to the upstream repos.

The report is generated by build_tools/generate_manifest_diff_report.py and uploaded to S3 by the manifest-diff.yml reusable workflow.

How it runs in CI

On pull_request and push events, multi_arch_ci.yml invokes manifest-diff.yml as a parallel sibling job. The reusable workflow auto-derives the start and end refs from the event payload — PR runs use the merge-base against the PR's base branch (rebase-safe via the GitHub Compare API); push runs use the branch tip before and after the push.

flowchart TD
    A[multi_arch_ci.yml fires] --> B{event_name}
    B -- pull_request --> P[merge-base via Compare API<br/>→ PR head SHA]
    B -- push --> U[branch tip before push<br/>→ new branch tip]
    P --> G[generate_manifest_diff_report.py]
    U --> G
    G --> O[upload_test_report_script.py]
    O --> H[S3 + step-summary link]

The sibling job is wired only for those two events because they're the ones whose payloads carry the implicit refs. A manual workflow_dispatch of multi_arch_ci.yml skips it; for ad-hoc runs, dispatch manifest-diff.yml directly — it exposes the full ref input surface.

Failure behavior

The reusable workflow sets continue-on-error: ${{ github.event_name != 'workflow_dispatch' }}:

• Under CI (push / pull_request from multi_arch_ci.yml): non-blocking — a script or API failure shows yellow on the run summary and never gates the build/test jobs running in parallel.
• Under direct workflow_dispatch of manifest-diff.yml: strict — real script regressions surface red, since the only reason to dispatch this workflow manually is to validate the script.

The upload and AWS-credentials steps are both gated on the report-generation step succeeding, so a failed report produces only the real error rather than a follow-on "no such file" upload failure.

Where the report lives

The report is uploaded to S3 by upload_test_report_script.py and linked from the job's step-summary tab. S3 layout, bucket selection, and credential routing (OIDC for base-repo, baseline credentials for fork PRs) are owned by workflow_outputs.md and s3_buckets.md.

Running it manually

workflow_dispatch

Trigger TheRock Manifest Diff Report on the Actions page. end_ref is required; pick exactly one of pr_base_ref, find_last_run, or start_ref to resolve the start (precedence: pr_base_ref > find_last_run > start_ref). See the description: fields on the inputs in manifest-diff.yml for the authoritative reference.

Local CLI

See generate_manifest_diff_report.py and run with --help for usage. Set GITHUB_TOKEN (any token with public_repo read scope) before running to avoid GitHub's 60 req/hr unauthenticated rate limit.

Out of scope

External orchestrator workflows in rocm-libraries / rocm-systems that drive TheRock's reusable workflows via setup_multi_arch.yml's external_repo input, and the rockrel release-driver flow (via multi_arch_release.yml), currently produce no manifest-diff; extending the report to those callers is tracked in #5219.

Code map

File	Role
.github/workflows/manifest-diff.yml	Reusable workflow: derives refs from caller event, runs script, uploads.
.github/workflows/multi_arch_ci.yml	Hosts the manifest_diff sibling job that calls manifest-diff.yml.
build_tools/generate_manifest_diff_report.py	Resolves start/end SHAs, walks submodules, renders the HTML report.
build_tools/github_actions/github_actions_api.py	gha_query_last_workflow_run() shared helper used by --find-last-run.
build_tools/github_actions/upload_test_report_script.py	S3 upload + step-summary link (shared with test reports).

Related

• ci_overview.md — overall multi-arch CI architecture.
• workflow_outputs.md — S3 layout used by the upload step.
• github_actions_debugging.md — debugging GitHub Actions runs.