Document (and unit test?) cross-repository workflow file architecture

[ScottTodd]

forking from discussion at https://github.com/ROCm/TheRock/pull/4366/changes#r3242863090

As for why this is set up this way, we should add some docs/diagrams explaining the architecture... It's roughly:

1. The entry point https://github.com/ROCm/rockrel/blob/main/.github/workflows/multi_arch_release.yml workflow runs in rockrel with uses: ROCm/TheRock/.github/workflows/multi_arch_release.yml@main. That uses the code from TheRock (currently with a floating pin to main but we could pin to a specific ref)
2. When that code runs uses: benc-uk/workflow-dispatch, the triggered workflow should also run in rockrel (https://github.com/ROCm/rockrel/actions), not in therock (https://github.com/ROCm/TheRock/actions). The default repo behavior of that action (https://github.com/benc-uk/workflow-dispatch#repo) is what we want - if we wanted to trigger in another repo then we'd need to specify it and provide a token.
3. For that triggered workflow to run, it needs a file in https://github.com/ROCm/rockrel/tree/main/.github/workflows. We use stub workflows like https://github.com/ROCm/rockrel/blob/main/.github/workflows/test_artifacts.yml that just forward their inputs through to e.g. uses: ROCm/TheRock/.github/workflows/test_artifacts.yml@main
4. We pass repository and ref to each workflow so rockrel can clarify that it wants the actions to checkout ROCm/TheRock and some specific ref (branch/tag/etc.) of TheRock, not the repository/ref of the entry point workflow (ROCm/rockrel + some commit there), see

   rockrel/.github/workflows/multi_arch_release.yml

   Line 61 in f4db554

   repository: "ROCm/TheRock"

Alternate designs are possible, and we can add unit tests and ref pinning across workflows to make such changes easier/safer.

See also:

• [Issue] Multi Arch Release: Trigger Native Install Test jobs fail — test_native_linux_packages_install.yml workflow missing in ROCm/rockrel TheRock#5647
• Add .github/workflows/test_artifacts.yml wrapper workflow #44
• Switch multi-arch releases to dispatch test_artifacts.yml TheRock#5212

---

Ideas for how to improve:

• Document the current setup more clearly, here in rockrel and/or in https://github.com/ROCm/TheRock/tree/main/docs/development somewhere. Could also reference such docs in the workflows themselves to make it harder to miss
• Add a unit test job in either/both repositories that checks for stub workflows with the correct inputs
• Add automation that generates stub workflows in this repository (would require granting a bot write access or at least PR creation access)
• Redesign how workflows are set up
  • Move/fork all release workflows here (dev/nightly), instead of sharing across repositories?

[ScottTodd]

Some raw design notes:

Unit test that checks that all release workflow descendants that use workflow_dispatch have a stub workflow in rockrel on the default branch that takes the same inputs.

Escape hatch / comments in the test about cross-repo changes and floating references? How to change inputs or delete/rename workflows across repositories without making the tests fail for unrelated PRs?

Could pin to a ref in rockrel and only update the pin if unit tests in rockrel pass. Dependabot or other automation for pin update PRs

Documentation explaining the stub workflow architecture, along with other details about release pipelines (dev releases, nightly releases, release promotion, differences between CI and CD, etc.)