[rusackas]

Summary

GitHub's merge queue rule type already worked through the existing raw ruleset payload path (github.rulesets[].rules[].type: merge_queue) since the top-level schema for rulesets is fully generic and the numeric-parameter coercion list already happened to include all five of merge_queue's integer fields. But it wasn't documented anywhere, and it couldn't be combined with any of the convenience-syntax keys (required_pull_request_reviews, branches, etc.) in the same ruleset entry, since raw and convenience syntax are mutually exclusive per entry. A project wanting a merge queue alongside e.g. required reviews had to hand-write the entire ruleset as a raw API payload, translating branches.includes into conditions.ref_name, etc.

This PR:

• Adds a merge_queue convenience key, so it composes with the rest of the convenience syntax (see example below).
• Documents both the new convenience key and the (already-working) raw payload rule type in the README's Rulesets section.
• Adds test coverage: convenience-syntax success, combining with another convenience rule, missing-field/invalid-enum validation errors, and a raw-passthrough regression test.

All seven merge_queue parameters are required by GitHub's Rulesets API, so the convenience syntax requires all of them too rather than guessing at undocumented defaults.

Example

github:
  rulesets:
    - name: "Merge Queue"
      type: branch
      required_pull_request_reviews:
        required_approving_review_count: 1
      merge_queue:
        check_response_timeout_minutes: 60
        grouping_strategy: ALLGREEN
        max_entries_to_build: 5
        max_entries_to_merge: 5
        merge_method: SQUASH
        min_entries_to_merge: 1
        min_entries_to_merge_wait_minutes: 5

Testing instructions

• pytest tests/github_rulesets.py (new tests: test_rulesets_convenience_merge_queue_*, test_rulesets_raw_merge_queue_rule_passes_through)
• ruff check / ruff format --check / mypy all pass on the changed files
• Verified against a real strictyaml schema load + payload-build pass (not just unit-test mocks) that a merge_queue ruleset round-trips to the exact shape GitHub's Rulesets API expects

No behavior changes to any existing rule types.

[ppkarwasz]

Nit: these values might be more useful as comments in the example configuration (like in “Merge buttons” then as notes. This way the documentation travels with the example.

[potiuk]

Tried to sandbox-test this and could not, but the reason isn't your change.

Rebased onto current main (the branch predates the --branch flag #127 added to asfyaml-run) and applied the README's example ruleset. GitHub rejected it:

Validation failed while creating ruleset 'Merge Queue': ["Invalid rule 'merge_queue': "]

I then posted the same rule directly to the REST API with a hand-written payload, bypassing the parser entirely, and got byte-identical output — while a plain pull_request ruleset creates fine on the same repository. So the payload your code builds isn't the problem; merge queue isn't available for a user-owned sandbox repo.

Run: https://github.com/potiuk/infrastructure-asfyaml/actions/runs/35316854577

This needs a run against apache/infrastructure-asfyaml-sandbox by a committer to be validated. Worth noting in docs/testing-a-change.md too — the fork self-testing path can't cover org-only features.

[rusackas]

@potiuk any idea who's qualified to run that? Pretty sure I can't do it :/

[potiuk]

@potiuk any idea who's qualified to run that? Pretty sure I can't do it :/

One of the infra people :)

[rusackas]

Thanks @potiuk. @Humbedooh any chance you could kick off a sandbox run on this one? Merge queue isn't available on user-owned repos, so the fork self-test path can't cover it.

[potiuk]

As described in https://github.com/apache/infrastructure-asfyaml/blob/main/docs/testing-a-change.md#testing-locally-instead - you need an organisation admin and the organisation has to have ability to use that feature.

You could likely @rusackas test it yourself - and provide evidences (as I did) - all you need you need an organisation in GitHub that you can test it with -> Preset I guess?

The documentation is pretty comprehensive - and basically all I did when I tested other changes was to ask my agent to "test this PR" the SKILL that I created should handle all the rest, including producing test report and linking to your runs showing how it works.

[rusackas]

Ahh, didn't realize a Preset org would work for this. Not sure I've got owner rights there though. And I hadn't spotted the sandbox-test skill in .claude/skills before, neat.

[potiuk]

SKILLs are all you need ;)

[rusackas]

Sandbox-tested at 922b0de (rebased onto current main — the branch predated #127's --branch flag on asfyaml-run, which the sandbox-test workflow requires).

Ran against apache-superset/infrastructure-asfyaml-sandbox (an org-owned repo — merge queue isn't available on a user-owned sandbox, which is why self-testing in a personal fork couldn't cover this). Applied:

github:
  rulesets:
    - name: "Merge Queue"
      type: branch
      required_pull_request_reviews:
        required_approving_review_count: 1
      merge_queue:
        check_response_timeout_minutes: 60
        grouping_strategy: ALLGREEN
        max_entries_to_build: 5
        max_entries_to_merge: 5
        merge_method: SQUASH
        min_entries_to_merge: 1
        min_entries_to_merge_wait_minutes: 5

Confirmed by reading /repos/apache-superset/infrastructure-asfyaml-sandbox/rulesets back afterward — a Merge Queue ruleset was created (enforcement: active, scoped to ~DEFAULT_BRANCH) containing a merge_queue rule with all 7 parameters matching exactly (merge_method: SQUASH, max_entries_to_build: 5, min_entries_to_merge: 1, max_entries_to_merge: 5, min_entries_to_merge_wait_minutes: 5, grouping_strategy: ALLGREEN, check_response_timeout_minutes: 60), combined correctly with the pull_request rule (required_approving_review_count: 1) from the same ruleset entry. As a bonus, the ruleset's own non_fast_forward/branch-protection rules then blocked a direct force-push I tried against the sandbox's main — confirming enforcement: active is genuinely active, not just reported.

Reset afterward: deleted the ruleset via the API (its own protection blocked the usual "push baseline, re-run" reset until it was gone), then re-ran against the baseline .asf.yaml to confirm nothing regenerates it. Rulesets list is back to empty, description back to baseline.

Dry run: https://github.com/rusackas/infrastructure-asfyaml/actions/runs/36967718339
Apply run: https://github.com/rusackas/infrastructure-asfyaml/actions/runs/36967773709
Reset run: https://github.com/rusackas/infrastructure-asfyaml/actions/runs/36967925281

[rusackas]

@potiuk sandbox test's done, details in the comment above. Had to use an apache-superset sandbox since merge queue needs an org-owned repo, exactly as you suspected. CI's green and it's already approved, so should be mergeable whenever you get a chance.

[potiuk]

cool. @Humbedooh -> there are a number of other PRs here as well, is there a way to get those reviews / merges done somewhat faster ? Generally speaking we now have tools that allow to test things in minutes (literally), so all we really need is somoene who has write access to decide if given feature should or should not be merged - and you can test it via your agent with:

test this PR

So I think all major blockers from quickly processing those PRs are gone? If the infrastructure team does not have enough capacity, I am sure there are a number of volunteers (starting with me) who would be happy to review and merge such requests (given some criteria that should be applied) - very similarly as we do with infrastructure-actions.

Can we do something to speed things up here and empower more PMCs to do more things with their actions?

I am not asking for "more work for you" - I am asking for ways to unblock obstacles - and I am oferring my help.