agents: document cross-branch workflow dispatch and draft PR merge (#4425) When workflows on `main` operate on another branch (such as `release/X.Y`), calling reusable workflows via `uses:` mixes `main` workflow definitions with target-branch scripts. In addition, merging a draft PR via `gh pr merge` fails unless the PR is marked ready first. Document cross-branch `gh workflow run --ref` dispatch, fast-fail ref parsing, and contextual `::error::` reporting in the workflow rules and review prompt, and instruct the merge skill to run `gh pr ready` before merging draft PRs.
diff --git a/.agents/rules/github_actions_workflows.md b/.agents/rules/github_actions_workflows.md index 820579a..02607e5 100644 --- a/.agents/rules/github_actions_workflows.md +++ b/.agents/rules/github_actions_workflows.md
@@ -41,6 +41,22 @@ release tag or a commit (e.g. in presubmit), use that exact tag or commit SHA value throughout. Never invent dummy version strings (e.g. `0.0.0-dev`) or create synthetic git tags to work around downstream logic. +* **Cross-Branch Workflow Dispatch (`gh workflow run`)**: When a default-branch + event (such as `issue_comment`) triggers work that operates on a specific + branch (e.g., `release/X.Y`), dispatch the target workflow onto that ref via + `gh workflow run <workflow> --repo "$REPO" --ref "$BRANCH"` (with job-level + `permissions: actions: write`) in the entry-point router workflow as soon as + the target branch is determined. Do not mix `main` workflows (`uses:`) with + release-branch checkouts or place re-dispatch logic inside the target + workflows. Name dispatch steps `"Dispatch: <Target Workflow Name>"` and + verify the target workflow's `workflow_dispatch.inputs` schema matches on + both `main` and the target branch. +* **No Silent Ref Fallbacks (`|| github.ref_name`)**: Never use fallback + expressions such as `${{ needs.parse.outputs.branch || github.ref_name }}` + that silently run a job against the wrong branch when an output is empty. + Fail fast in the parsing step with a contextual `::error::` message + (including relevant identifiers such as issue number and title) when a + required output cannot be determined. * **No `--stamp` or `--embed_label` on Pull Requests**: Only pass `--stamp` and `--embed_label` on release builds, never on `pull_request` builds, to avoid busting remote/RBE caching.
diff --git a/.agents/skills/merge-pr/SKILL.md b/.agents/skills/merge-pr/SKILL.md index 056e51c..7c18194 100644 --- a/.agents/skills/merge-pr/SKILL.md +++ b/.agents/skills/merge-pr/SKILL.md
@@ -9,6 +9,10 @@ 1. **Enqueue for Merge**: Run `gh pr merge <pr_number> --repo bazel-contrib/rules_python --auto --squash`. + - **Draft PRs**: If the PR is a draft (`isDraft: true`), mark it ready for + review first via `gh pr ready <pr_number> --repo + bazel-contrib/rules_python` (otherwise `gh pr merge` fails with + `Pull Request is still a draft`). - **Force / Admin Merge**: **CRITICAL**: Only pass `--admin` (e.g., `gh pr merge <pr_number> --repo bazel-contrib/rules_python --admin --squash`) with explicit user consent ("force merge", "admin merge", or
diff --git a/.agents/skills/review-code/review-workflows-prompt.md b/.agents/skills/review-code/review-workflows-prompt.md index 8510b9b..72b0ce2 100644 --- a/.agents/skills/review-code/review-workflows-prompt.md +++ b/.agents/skills/review-code/review-workflows-prompt.md
@@ -23,20 +23,27 @@ use `imports = ["../../.github/workflows"]` in `BUILD.bazel`, and do not modify `sys.path`. 7. Verify console messaging: ensure scripts use GHA workflow command syntax - (e.g. `::error::`, `::warning::`, `::notice::`, `::group::`). -8. Verify non-trivial scripts (such as multi-line shell or Python logic) are + (e.g. `::error::`, `::warning::`, `::notice::`, `::group::`) and include + identifying context (such as issue/PR numbers) in error messages. +8. Verify cross-branch dispatch and ref handling: ensure workflows triggered on + `main` that operate on another branch (such as `release/X.Y`) dispatch onto + that ref via `gh workflow run ... --ref "$BRANCH"` from the router workflow + (with step name `"Dispatch: <Workflow Name>"`), never use silent ref + fallbacks (`|| github.ref_name`), and match `workflow_dispatch.inputs` on + the target branch. +9. Verify non-trivial scripts (such as multi-line shell or Python logic) are factored into standalone files (e.g. `.sh` or `.py` files) rather than inlined in workflow YAML steps (`run: |`), shell scripts, or command invocations via heredocs (`<< 'EOF'`) or `-c` flags (`bash -c`, `python3 -c`). -9. Verify local composite actions: ensure workflows use local composite action - wrappers (specifically `uses: ./.github/actions/setup-bazel`) rather than - invoking `bazel-contrib/setup-bazel` directly. If a workflow calls - `bazel-contrib/setup-bazel` directly, replace it with - `uses: ./.github/actions/setup-bazel` (updating - `.github/actions/setup-bazel/action.yaml` if new defaults or inputs are - needed). -10. Audit for injection and security vulnerabilities: +10. Verify local composite actions: ensure workflows use local composite action + wrappers (specifically `uses: ./.github/actions/setup-bazel`) rather than + invoking `bazel-contrib/setup-bazel` directly. If a workflow calls + `bazel-contrib/setup-bazel` directly, replace it with + `uses: ./.github/actions/setup-bazel` (updating + `.github/actions/setup-bazel/action.yaml` if new defaults or inputs are + needed). +11. Audit for injection and security vulnerabilities: - Require explicit top-level `permissions:` (`{}` or minimal scopes) in all workflows, and explicit job-level permissions for reusable workflow calls or write jobs (`actions/missing-workflow-permissions`).