Skip to content

Org-standard required-check stubs need merge_group triggers: agent-shield and dependency-audit block merge-queue adoption in consumer repos #1157

Closed
#1158
Closed
Org-standard required-check stubs need merge_group triggers: agent-shield and dependency-audit block merge-queue adoption in consumer repos#1157
#1158
Labels
dev-leadFor dev-lead agent pickupenhancementFeature requests

Description

@don-petry
don-petry
opened on Sep 21, 2026

Summary

petry-projects/.github-private is adopting a GitHub merge queue to end the rebase treadmill documented in petry-projects/.github-private#1864 (one merge to main forced a full re-review of every other open PR; ≈154 forced re-reviews over 48h, zero merges).

A merge queue only merges a PR once its required status checks report on the queue's temporary gh-readonly-queue/* ref, which means every workflow providing a required check must trigger on the merge_group event. Two of the affected workflows are org-standard thin caller stubs whose triggers this repo owns:

  • standards/workflows/agent-shield.yml → provides required check agent-shield / AgentShield
  • standards/workflows/dependency-audit.yml → provides required check dependency-audit / Detect ecosystems

Both stubs carry the standing instruction:

You MUST NOT change: trigger events, the uses: line, or the job name (used as a required status check).

So the consumer repo cannot add merge_group itself without violating the stub contract. The change belongs here, in the templates.

What is needed

Add merge_group to the trigger block of both stub templates, alongside the existing push / pull_request triggers:

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  merge_group:

The reusables themselves are workflow_call and need no change — they are indifferent to the outer event. The job names must stay exactly as they are, since they are the required-check contexts.

Acceptance Criteria

  1. standards/workflows/agent-shield.yml and standards/workflows/dependency-audit.yml trigger on merge_group in addition to their current events.
  2. Job names are unchanged, so the required-check contexts (agent-shield / AgentShield, dependency-audit / Detect ecosystems) still match.
  3. The stub headers' "MUST NOT change: trigger events" guidance is updated to note that merge_group is part of the standard trigger set, so a future consumer-side sync does not strip it and a future reviewer does not flag it as drift.
  4. Any stub-drift checker that compares consumer triggers against the template accepts the new trigger set (scripts/caller_stub_freeze.sh / template_stub_drift.sh / fleet_stub_drift.sh in the consumer repo reason about this — confirm none of them pin the old trigger list).
  5. standards/ci-standards.md states that org-standard required-check workflows must support merge_group, so this is a property of the standard rather than a one-off patch for one repo.

Why it is worth doing at the standard level

Any repo in the org that later adopts a merge queue hits exactly this wall. Making merge_group part of the standard trigger set for required-check stubs means the next adopter needs no cross-repo change at all.

Sequencing

Blocking prerequisite for petry-projects/.github-private#1864's merge-queue step. Note that repo has already dropped strict_required_status_checks_policy (2026-09-21), which removed the forced-rebase driver; the queue restores the "tested against the post-merge state" guarantee that strict was approximating. Until both land, that repo is running with neither — so this is time-sensitive rather than merely tidy.

References

  • petry-projects/.github-private#1864 — the treadmill measurement and the approved merge-queue decision
  • petry-projects/.github-private#1866 — a related defect where a sync rewrote stub fields it was told to preserve; the trigger set must not become a second instance of that
  • GitHub docs: merge queue requires merge_group event support for required checks

Activity

  1. don-petry
    added
    enhancementFeature requests
    dev-leadFor dev-lead agent pickup
    on Sep 21, 2026

  2. don-petry commented on Sep 21, 2026

    @don-petry
    don-petry
    on Sep 21, 2026
    ContributorAuthor

    Dev-Lead Implementation Plan

    Issue: #1157 — Org-standard required-check stubs need merge_group triggers: agent-shield and dependency-audit block merge-queue adoption in consumer repos

    Scope

    Add merge_group to the trigger block of the two org-standard required-check caller stubs (agent-shield.yml, dependency-audit.yml), update their "MUST NOT change" header guidance to note merge_group is part of the standard trigger set, and codify in ci-standards.md that org-standard required-check workflows must support merge_group — so merge-queue adoption needs no cross-repo change.

    Implementation Checklist

    • standards/workflows/agent-shield.yml — add merge_group: to on:; job name agent-shield unchanged
    • standards/workflows/dependency-audit.yml — add merge_group: to on:; job name dependency-audit unchanged
    • Update both stub headers' "MUST NOT change: trigger events" guidance to note merge_group is part of the standard trigger set (so a sync doesn't strip it / a reviewer doesn't flag it as drift — the #1866 concern)
    • standards/ci-standards.md — state org-standard required-check workflows must support merge_group (property of the standard, not a one-off)
    • AC Add workflow, environment, and orchestration guidance #4 confirmation: the on:-block drift checkers (caller_stub_freeze.sh / template_stub_drift.sh / fleet_stub_drift.sh, and the source-side check_stub_surface_drift in compliance-audit.sh) compare the on: block against the template dynamically (hash/normalize), pinning no fixed trigger list — so they accept the new trigger set once the template carries it. No change needed; documented in report.

    Tests to Write

    • test/scripts/standards-templates/merge-group-required-checks.bats — template guard asserting both required-check stub templates carry a merge_group: trigger and their required-check job names are unchanged (mirrors the existing vform-pins.bats / s7635-secrets-inherit.bats guards)

    Test Command

    bats --print-output-on-failure test/scripts/standards-templates/

  3. don-petry commented on Sep 21, 2026

    @don-petry
    don-petry
    on Sep 21, 2026
    ContributorAuthor

    Dev-Lead: Progress (in progress — not yet durable)

    Provisional. Nothing is pushed yet; the automation posts the authoritative
    completion record (with PR number + head SHA) after the push. Treat the notes
    below as intent, not delivered results.

    Plan Execution (intended)

    • Added merge_group to the on: trigger set of both required-check stubs.
    • Updated both stub headers' "MUST NOT change: trigger events" guidance to note
      merge_group is part of the standard trigger set (so a sync won't strip it and
      a reviewer won't flag it as drift — the #1866 concern).
    • Added a "Required-check stubs must support merge_group" subsection to
      standards/ci-standards.md (Tier-1 on:-surface section), making it a property
      of the standard.
    • Added a template-guard bats test mirroring the existing vform-pins /
      s7635-secrets-inherit guards.
    • AC Add workflow, environment, and orchestration guidance #4: the on:-block drift checkers (caller_stub_freeze.sh,
      template_stub_drift.sh, fleet_stub_drift.sh, and source-side
      check_stub_surface_drift) compare the on: block against the template
      dynamically (blob-SHA / byte-identity), pinning no fixed trigger list — they
      accept the new trigger set once the template carries it. No change needed.

    Files touched (this workspace, not yet pushed)

    • standards/workflows/agent-shield.yml: merge_group: trigger + header note.
    • standards/workflows/dependency-audit.yml: merge_group: trigger + header note.
    • standards/ci-standards.md: required-check merge_group subsection.
    • test/scripts/standards-templates/merge-group-required-checks.bats: new guard.

    Local check output (provisional — not the pushed run)

    bats test/scripts/standards-templates/ → 10 tests, all ok (incl. 3 new merge_group guards)
compliance-audit stub-surface / centralized-stub-pins / s7637 + deploy dry-run/emit-vform → ok
.dev-lead/scripts/dev-lead-lint.sh → all checks passed
YAML parse: both stubs on-keys include merge_group; jobs unchanged (agent-shield, dependency-audit)

    Notes

    Behavior-preserving for existing push/PR runs; the only new behavior is triggering
    on the merge-queue event. Reusables are workflow_call and unchanged. Required-check
    job names are unchanged, so branch-protection contexts still match.

  4. don-petry commented on Sep 21, 2026

    @don-petry
    don-petry
    on Sep 21, 2026
    ContributorAuthor

    Dev-Lead: Implementation Complete — PR #1158

    The implementation for issue #1157 is durable: commits are pushed and a pull request is open. This record is backed by verifiable artifacts you can confirm in one click.

    Review happens on the PR. Acceptance criteria and test results are evidenced by the PR's diff and CI checks — not asserted here. If a later stage fails, this claim is retracted in place.

  5. don-petry
    added a commit that references this issue on Sep 21, 2026

    feat: implement issue #1157 — Org-standard required-check stubs need …

    b16e764
  6. don-petry
    closed this as completedin #1158on Sep 21, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    dev-leadFor dev-lead agent pickupenhancementFeature requests

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions