CNTRLPLANE-3716: Update GitHub Actions docs with slash-command workflows

[bryan-cox]

What this PR does / why we need it:

Updates the GitHub Actions documentation page (docs/content/how-to/ci/github-actions.md) with:

• 🤖 New PR Slash Commands section documenting /address-review-comments, /rebase, and /restructure-commits
• 🔧 Added missing workflows to the Other table (gocacheprog-test, validate-cpo-overrides)
• ✨ Polished the page with MkDocs admonitions, emojis, and a collapsible example section for consistency with other CI docs

Which issue(s) this PR fixes:

Fixes https://issues.redhat.com/browse/CNTRLPLANE-3716

Special notes for your reviewer:

Docs-only change. MkDocs strict build passes.

Checklist:

• Subject and description added to both, commit and PR.
• Relevant issues have been referenced.
• This change includes docs.
• This change includes unit tests.

Summary by CodeRabbit

• Documentation
  • Reworked the GitHub Actions guide with a new “Reusable Workflow Architecture” section and clearer trigger/pattern explanations.
  • Expanded the workflow catalog with Code Quality plus Testing and Documentation tables, including clarified guidance on which workflows are reusable.
  • Added a “PR Slash Commands” section with required permissions, command-to-workflow mappings, an ordered “how it works” flow, and concurrency cancellation tips.
  • Updated “Adding a New Workflow” instructions with post-merge run guidance, refined “pin to @main” notes, and improved example snippets.

[openshift-merge-bot]

Pipeline controller notification
This repo is configured to use the pipeline controller. Second-stage tests will be triggered either automatically or after lgtm label is added, depending on the repository configuration. The pipeline controller will automatically detect which contexts are required and will utilize /test Prow commands to trigger the second stage.

For optional jobs, comment /test ? to see a list of all defined jobs. To trigger manually all jobs from second stage use /pipeline required command.

This repository is configured in: LGTM mode

[openshift-ci-robot]

@bryan-cox: This pull request references CNTRLPLANE-3716 which is a valid jira issue.

Warning: The referenced jira issue has an invalid target version for the target branch this PR targets: expected the task to target the "5.0.0" version, but no target version was set.

Details

In response to this:

What this PR does / why we need it:

Updates the GitHub Actions documentation page (docs/content/how-to/ci/github-actions.md) with:

• 🤖 New PR Slash Commands section documenting /address-review-comments, /rebase, and /restructure-commits
• 🔧 Added missing workflows to the Other table (gocacheprog-test, validate-cpo-overrides)
• ✨ Polished the page with MkDocs admonitions, emojis, and a collapsible example section for consistency with other CI docs

Which issue(s) this PR fixes:

Fixes https://issues.redhat.com/browse/CNTRLPLANE-3716

Special notes for your reviewer:

Docs-only change. MkDocs strict build passes.

Checklist:

• Subject and description added to both, commit and PR.
• Relevant issues have been referenced.
• This change includes docs.
• This change includes unit tests.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[openshift-ci]

Skipping CI for Draft Pull Request.
If you want CI signal for your change, please convert it to an actual PR.
You can still manually trigger a test run with /test all

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: f4e9cb12-3d20-46e0-a0e1-8163e15ce5a0

📥 Commits

Reviewing files that changed from the base of the PR and between cf9b59e and 5426559.

⛔ Files ignored due to path filters (1)

• docs/content/reference/aggregated-docs.md is excluded by !docs/content/reference/aggregated-docs.md

📒 Files selected for processing (1)

• docs/content/how-to/ci/github-actions.md

---

📝 Walkthrough

Walkthrough

The docs/content/how-to/ci/github-actions.md page is reorganized and expanded. It adds a reusable workflow architecture section, new testing and documentation tables, an updated other-workflows table, and a PR slash commands section. The workflow authoring guidance is expanded with post-merge run placement, caller pinning guidance, and example caller and reusable workflow snippets.

Suggested Reviewers

• csrwng
• jparrill

🚥 Pre-merge checks | ✅ 11

✅ Passed checks (11 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately reflects the docs update and highlights the new slash-command workflow content.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Stable And Deterministic Test Names	✅ Passed	Docs-only PR; the changed markdown file has no Ginkgo test titles or dynamic test-name patterns.
Test Structure And Quality	✅ Passed	PR is docs-only; no Ginkgo test code was added or changed, so the test-quality check is not applicable.
Topology-Aware Scheduling Compatibility	✅ Passed	Docs-only change to github-actions.md; no deployment manifests, operator code, or controllers were modified, so no topology-aware scheduling risk.
Ipv6 And Disconnected Network Test Compatibility	✅ Passed	The PR only updates a docs Markdown page; no Ginkgo/e2e test files or runnable network-sensitive code were added or changed.
No-Weak-Crypto	✅ Passed	PASS: The PR only updates a Markdown docs page, and the patch contains no MD5/SHA1/DES/RC4/3DES/Blowfish/ECB, custom crypto, or secret-comparison code.
Container-Privileges	✅ Passed	No changed YAML manifest in the PR contains privileged/host* or SYS_ADMIN flags; the visible diff is docs-focused.
No-Sensitive-Data-In-Logs	✅ Passed	Docs-only changes; targeted search found no passwords, tokens, keys, PII, session IDs, or internal hostnames exposed.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docs/content/how-to/ci/github-actions.md`:
- Around line 32-33: The “all workflows” statement in the GitHub Actions docs is
too broad and conflicts with the trigger-specific workflows described on this
page. Update the wording in the affected prose to use a narrower claim such as
“most reusable PR workflows” or explicitly mention the exceptions for
`workflow_run`, PR-comment, and `main`-only workflows, keeping the description
aligned with the workflows documented alongside it.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Central YAML (inherited)

Review profile: CHILL

Plan: Enterprise

Run ID: 95dad2ee-da75-45f3-9ce3-eaba14758208

📥 Commits

Reviewing files that changed from the base of the PR and between bc3bda9 and 0a7cd1d.

📒 Files selected for processing (1)

• docs/content/how-to/ci/github-actions.md

[hypershift-jira-solve-ci]

I now have the full root cause. The PR modifies docs/content/how-to/ci/github-actions.md, which is one of the 307 documentation files aggregated by the docs-aggregator tool into docs/content/reference/aggregated-docs.md. The make generate update step runs this aggregator, which regenerates aggregated-docs.md with the new content from the PR's changes. But the PR didn't include the updated aggregated-docs.md, so the git dirty check at the end of verification detects a difference and fails.

Test Failure Analysis Complete

Job Information

• Prow Job: verify / Verify (GitHub Actions)
• Build ID: 28104826709 / Job 83216096583
• Target: make generate update → make verify pipeline
• PR: CNTRLPLANE-3716: Update GitHub Actions docs with slash-command workflows #8822 — CNTRLPLANE-3716: Update GitHub Actions docs with slash-command workflows
• Commit: cf9b59e

Test Failure Analysis

Error

docs/content/reference/aggregated-docs.md: needs update
##[error]Process completed with exit code 1.

Summary

The PR modifies docs/content/how-to/ci/github-actions.md (updating the GitHub Actions documentation with slash-command workflows, emojis, admonitions, and new sections) but does not include the corresponding regenerated docs/content/reference/aggregated-docs.md. The verify workflow runs make generate update, which invokes hack/tools/docs-aggregator/main.go — a tool that walks all 307 markdown files under docs/content/ and concatenates them into aggregated-docs.md. Since the PR changed a source file without committing the regenerated aggregated output, the final git diff --exit-code HEAD -- check detects the stale file and exits with code 1.

Root Cause

The docs-aggregator tool (hack/tools/docs-aggregator/main.go) scans every .md file under docs/content/, sorts them, strips markdown links/images, and writes the combined output to docs/content/reference/aggregated-docs.md. This is executed during make generate update (the first step of the verify workflow).

PR #8822 modifies docs/content/how-to/ci/github-actions.md with substantial content changes (new "PR Slash Commands" section, emoji headings, MkDocs admonition blocks, expanded workflow examples, additional table entries for gocacheprog-test.yaml and validate-cpo-overrides.yaml). When the aggregator re-runs during CI, it produces a new aggregated-docs.md that incorporates these changes. Since the PR branch does not contain the updated aggregated-docs.md, the post-verification git-dirty check (git update-index --refresh → git diff --exit-code HEAD --) detects the difference and fails.

This is a generated-file-not-committed error — the author edited a source doc but forgot to run make generate update (or make generate) locally and commit the resulting aggregated-docs.md.

Recommendations

1. Run make generate update locally on the PR branch and commit the regenerated docs/content/reference/aggregated-docs.md:

   make generate update
   git add docs/content/reference/aggregated-docs.md
   git commit -m "Regenerate aggregated-docs.md"

2. Push the updated commit to the PR branch — the verify workflow will pass on the next run.

3. For future docs-only PRs: Always run make generate update after editing any file under docs/content/. The docs-aggregator picks up all markdown changes, so any documentation edit requires regenerating the aggregated file.

Evidence

Evidence	Detail
Failed step	git diff --exit-code HEAD -- (verify-reusable.yaml post-generate dirty check)
Dirty file	docs/content/reference/aggregated-docs.md: needs update
PR changed file	docs/content/how-to/ci/github-actions.md (only file in PR)
Generator tool	hack/tools/docs-aggregator/main.go — aggregates all 307 docs under docs/content/
Generator output	Successfully aggregated 307 documentation files to docs/content/reference/aggregated-docs.md (at 14:18:53 UTC)
Trigger step	make generate update ran the aggregator; make staticcheck, make fmt, make vet all passed
Exit code	1 (from git diff --exit-code HEAD -- detecting uncommitted generated changes)

---

[bryan-cox]

/verified by @bryan-cox

I looked at the deployment link and it looks fine to me.

[openshift-ci-robot]

@bryan-cox: This PR has been marked as verified by @bryan-cox.

Details

In response to this:

/verified by @bryan-cox

I looked at the deployment link and it looks fine to me.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the openshift-eng/jira-lifecycle-plugin repository.

[celebdor]

Very nice improvements and additions for the gaps! Thanks, Bryan!
/lgtm

[openshift-merge-bot]

Pipeline controller notification

No second-stage tests were triggered for this PR.

This can happen when:

• The changed files don't match any pipeline_run_if_changed patterns
• All files match pipeline_skip_if_only_changed patterns
• No pipeline-controlled jobs are defined for the main branch

Use /test ? to see all available tests.

[openshift-ci]

[APPROVALNOTIFIER] This PR is APPROVED

This pull-request has been approved by: bryan-cox, celebdor

The full list of commands accepted by this bot can be found here.

The pull request process is described here

Details

Needs approval from an approver in each of these files:

• OWNERS [bryan-cox]

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[openshift-ci]

@bryan-cox: all tests passed!

Full PR test history. Your PR dashboard.

Details

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository. I understand the commands that are listed here.