feat(workflows): add ingress dynamic routing for obs and docs by fr4nc1sc0-r4m0n · Pull Request #1104 · elastic/oblt-aw

fr4nc1sc0-r4m0n · 2026-06-01T18:07:06Z

Summary

Introduces ingress dynamic routing for Observability and Documentation agentic workflows. Consumer repos get a single trigger and entrypoint per org instead of one client workflow per control-plane reusable, which cuts PR check noise. The control plane runs aw-prelude once per ingress invocation and dispatches only registry-eligible route-* jobs to individual oblt-aw-* / docs-aw-* reusables.

69 files changed (+2,475 / −1,119) across 5 commits on this branch.

Architecture

flowchart LR
  subgraph consumer [Consumer repo]
    T[trigger-oblt-aw.yml / trigger-docs-aw.yml]
    E[oblt-aw.yml / docs-aw.yml]
  end
  subgraph control [elastic/oblt-aw]
    I[oblt-aw-ingress.yml / docs-aw-ingress.yml]
    P[aw-prelude.yml]
    W[oblt-aw-* / docs-aw-* reusables]
  end
  T -->|workflow_dispatch| E
  E -->|workflow_call| I
  I --> P
  I -->|route-* jobs| W

Event flow: repository events → unified trigger → workflow_dispatch to org entrypoint → workflow_call to ingress → prelude + gated route-* → individual GH-AW wrappers (no prelude in wrappers).

Control-plane ingress workflows

Workflow	Route jobs	Purpose
`oblt-aw-ingress.yml` (new)	15 `route-*` jobs	agent-suggestions, autodoc, automerge, dependency-review, duplicate-issue-detector, issue-triage, issue-fixer, mention-in-issue, security (detector/fixer/triage), resource-not-accessible-by-integration (detector/fixer/triage), estc-pr-buildkite-detective
`docs-aw-ingress.yml` (new)	3 `route-*` jobs	ai-menu, pr-ai-menu-collect, pr-ai-menu

aw-prelude.yml — Prelude is ingress-only; reads dashboard enabled-workflows / effective-raw, optional allow lists, and token policy. Individual oblt-aw-* / docs-aw-* workflows no longer call prelude (enforced by validate_aw_workflow_prelude.py).
Ephemeral tokens — ingress-token-policy / Vault create-token only on routes that need special-permission tokens; removed unused pass-through inputs on workflows that never mint tokens.
oblt-aw-automerge.yml — Restored if gates on approve/automerge jobs so they skip when PR validation or dependency-collection checks fail.

All existing oblt-aw-* and docs-aw-* control-plane reusables were updated to accept relayed ingress context (event payload, allow lists, prelude outputs) instead of running their own prelude.

Client workflow template (distributed)

Observability (.github/remote-workflow-template/obs/):

Added: trigger-oblt-aw.yml, oblt-aw.yml
Removed: 15 per-workflow trigger-oblt-aw-*.yml files (agent-suggestions, autodoc, automerge, dependency-review, duplicate-issue-detector, estc-pr-buildkite-detective, issue-fixer, issue-triage, mention-in-issue, security ×3, resource-not-accessible ×3)

Documentation (.github/remote-workflow-template/docs/):

Added: trigger-docs-aw.yml, docs-aw.yml
Removed: trigger-docs-aw-ai-menu.yml, trigger-docs-aw-pr-ai-menu.yml, trigger-docs-aw-pr-ai-menu-collect.yml

Client trigger behavior (follow-up commits):

Fire-and-forget dispatch — Triggers no longer wait for entrypoint completion; on PRs they post a commit status (oblt-aw/entrypoint or docs equivalent) linking to the dispatched entrypoint run.
Same-repo dispatch — Client triggers use GITHUB_TOKEN (not Vault) for entrypoint workflow_dispatch.
Docs workflow_run loop guard — Privileged re-dispatch leg runs only when the completed trigger run originated from pull_request, matching ingress route-pr-ai-menu gating (prevents infinite workflow_run chains).

Registry and validation

config/obs/workflow-registry.json / config/docs/workflow-registry.json — Each workflow entry now declares ingress_routes (route id, optional allowed_bot_users_from, etc.) instead of a separate top-level routing table.
scripts/oblt_aw_route_specs.py (new) — Parses ingress_routes, flattens route specs, validates registry ↔ ingress route-* jobs ↔ workflow files.
scripts/validate_ingress_registry.py (new) — CI entrypoint for obs + docs registry/ingress alignment.
scripts/resolve_control_plane_workflow_id.py — Removed (superseded by route specs).
scripts/workflow_registry.py — Uses ingress_routes for control-plane workflow file discovery.
scripts/validate_aw_workflow_prelude.py — Prelude allowed only in ingress workflows, not in individual wrappers.
.github/workflows/ci.yml — New step: Validate ingress route registries.

Documentation and agent guidance

New: docs/workflows/oblt-aw-ingress.md, docs/workflows/docs-aw-ingress.md
Updated: oblt-aw-client-template.md, docs-aw-client-template.md, aw-prelude.md, onboarding, workflow README, dashboard format, sync-control-plane-dashboard
AGENTS.md, .cursor/rules/protected-oblt-aw-workflow.mdc — Client entrypoints only via unified trigger + entrypoint; no new per-workflow triggers

Tests

tests/test_oblt_aw_route_specs.py (new) — Registry parsing, legacy migration errors, ingress alignment
Updated: test_validate_aw_workflow_prelude.py, test_workflow_registry.py, test_build_target_operations.py

Commits on this branch

Commit	Description
`651bf1e`	Core ingress routing, unified client triggers, registry `ingress_routes`, validation scripts
`6332a87`	Automerge: restore verify / dependency-collection job gates
`e1cfd07`	Client trigger: fire-and-forget dispatch + PR commit status link
`837e356`	Token policy only where `create-token` runs; drop unused ingress inputs
`df69fea`	Docs trigger: prevent infinite `workflow_run` re-dispatch

Test plan

python3 -m pytest tests/test_oblt_aw_route_specs.py tests/test_validate_aw_workflow_prelude.py tests/test_workflow_registry.py tests/test_build_target_operations.py
Pre-commit hooks (yamllint, actionlint, ruff, mypy)
CI green on this PR
Roll out to a test consumer via distribute-client-workflow and compare PR check footprint before/after
Update branch-protection required checks if they still reference retired per-workflow trigger names

Risks / rollout

Consumer repos must migrate from per-workflow client triggers to unified entrypoints via distribution; retired trigger-oblt-aw-* / trigger-docs-aw-* files are removed on sync.
Branch-protection required checks may reference retired workflow names and need updating during rollout.
Ingress runs more routing logic in one workflow; misconfigured ingress_routes or missing route-* jobs are caught by CI validation.

Related issue: https://github.com/elastic/observability-robots/issues/4595

Replace per-workflow client triggers with unified trigger-oblt-aw.yml and trigger-docs-aw.yml entrypoints that dispatch to oblt-aw-ingress.yml and docs-aw-ingress.yml. Centralize aw-prelude in ingress route jobs; extend workflow registry with ingress_routes and add validation scripts. Why: Reduce PR check noise by consolidating client entrypoints and routing eligible workflows from registry-driven ingress jobs. Validation: pytest for route specs, prelude, and registry (61 passed). Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot

Pull request overview

This PR migrates Observability and Docs agentic workflows to an ingress-based dynamic routing model, centralizing aw-prelude execution in org-specific ingress workflows and moving route eligibility/gating to route-* jobs driven by workflow-registry.json.

Changes:

Introduces oblt-aw-ingress.yml / docs-aw-ingress.yml and updates control-plane wrappers to be ingress-routed (no per-wrapper prelude).
Replaces per-workflow client triggers with unified trigger + entrypoint templates (trigger-*-aw.yml + *-aw.yml) in the remote workflow templates.
Extends registry format with ingress_routes and adds Python validation/route-spec parsing to keep ingress jobs, registry entries, and workflow files consistent.

Reviewed changes

Copilot reviewed 69 out of 69 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
tests/test_workflow_registry.py	Updates registry indexing tests to align with `ingress_routes`-derived workflow mapping.
tests/test_validate_aw_workflow_prelude.py	Updates validation tests for “prelude only in ingress” model.
tests/test_oblt_aw_route_specs.py	Adds unit/integration tests for new ingress route-spec parsing and validation.
tests/test_build_target_operations.py	Updates distribution/build-target expectations for unified trigger/entrypoint templates.
scripts/workflow_registry.py	Switches registry parsing/indexing from `control_plane_workflows` to `ingress_routes`.
scripts/validate_ingress_registry.py	Adds CLI validator ensuring ingress route jobs match registry and workflow files.
scripts/validate_aw_workflow_prelude.py	Updates validation rules: wrappers must not call prelude; ingress must include prelude + `route-*`.
scripts/resolve_control_plane_workflow_id.py	Removes legacy “resolve compound id by wrapper file” script (no longer needed).
scripts/oblt_aw_route_specs.py	Adds parser/validator for `ingress_routes` and ingress `route-*` job id extraction.
README.md	Updates top-level description of docs templates to unified entrypoints.
docs/workflows/sync-control-plane-dashboard.md	Updates registry schema references to `ingress_routes`.
docs/workflows/README.md	Updates docs index to include ingress and new template names.
docs/workflows/oblt-aw-ingress.md	Documents the new Observability ingress workflow contract and routing behavior.
docs/workflows/oblt-aw-client-template.md	Updates consumer template docs to unified trigger + entrypoint model.
docs/workflows/docs-aw-pr-ai-menu.md	Updates docs PR menu workflow docs to reflect ingress routing.
docs/workflows/docs-aw-ingress.md	Documents the new Docs ingress workflow contract and routing behavior.
docs/workflows/docs-aw-client-template.md	Updates consumer template docs to unified trigger + entrypoint model and split PR menu pattern.
docs/workflows/docs-aw-ai-menu.md	Updates docs issue menu workflow docs to reflect ingress routing.
docs/workflows/aw-prelude.md	Updates prelude docs to “read-only + ingress-owned gating” contract.
docs/operations/control-plane-dashboard-format.md	Updates dashboard format docs to reflect ingress-based gating/registration.
docs/onboarding/adopting-agentic-workflows.md	Updates onboarding steps for ingress-route registration model.
config/obs/workflow-registry.json	Migrates Observability registry entries to `ingress_routes` (incl. allow-list hints).
config/docs/workflow-registry.json	Migrates Docs registry entries to `ingress_routes`.
AGENTS.md	Updates contributor guidance for the unified trigger/entrypoint + ingress routing architecture.
.github/workflows/oblt-aw-security-triage.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-security-fixer.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-security-detector.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-triage.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-fixer.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-resource-not-accessible-by-integration-detector.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-mention-in-issue.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-issue-triage.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-issue-fixer.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-ingress.yml	Adds Observability ingress workflow with `aw-prelude` + registry-driven `route-*` jobs.
.github/workflows/oblt-aw-estc-pr-buildkite-detective.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-duplicate-issue-detector.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-dependency-review.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-automerge.yml	Removes per-wrapper prelude; switches to ingress-relayed payload parsing.
.github/workflows/oblt-aw-autodoc.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/oblt-aw-agent-suggestions.yml	Removes per-wrapper prelude + in-wrapper gating; accepts ingress-relayed inputs.
.github/workflows/docs-aw-pr-ai-menu.yml	Removes per-wrapper prelude; uses ingress-relayed event context for gating/IDs.
.github/workflows/docs-aw-pr-ai-menu-collect.yml	Removes per-wrapper prelude; uses ingress-relayed event context.
.github/workflows/docs-aw-ingress.yml	Adds Docs ingress workflow with `aw-prelude` + `route-*` jobs.
.github/workflows/docs-aw-ai-menu.yml	Removes per-wrapper prelude; uses ingress-relayed event context for gating/IDs.
.github/workflows/ci.yml	Adds ingress registry validation step to CI.
.github/workflows/aw-prelude.yml	Updates prelude contract: no per-wrapper compound-id resolution; ingress passes event name.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw.yml	Adds unified Observability trigger that dispatches entrypoint with relayed event JSON.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-security-triage.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-security-fixer.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-security-detector.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-resource-not-accessible-by-integration-triage.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-resource-not-accessible-by-integration-fixer.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-resource-not-accessible-by-integration-detector.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-mention-in-issue.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-issue-triage.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-issue-fixer.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-estc-pr-buildkite-detective.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-duplicate-issue-detector.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-dependency-review.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-automerge.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-autodoc.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/trigger-oblt-aw-agent-suggestions.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/obs/.github/workflows/oblt-aw.yml	Adds unified Observability entrypoint that calls `oblt-aw-ingress.yml`.
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw.yml	Adds unified Docs trigger that dispatches entrypoint with relayed event JSON (incl. workflow_run).
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-pr-ai-menu.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-pr-ai-menu-collect.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw-ai-menu.yml	Removes legacy per-workflow client trigger template.
.github/remote-workflow-template/docs/.github/workflows/docs-aw.yml	Adds unified Docs entrypoint that calls `docs-aw-ingress.yml`.
.cursor/rules/protected-oblt-aw-workflow.mdc	Updates guardrails to reflect unified entrypoints (no per-workflow triggers).

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Re-add if conditions on approve and automerge so they skip when PR validation or dependency collection checks fail. Co-authored-by: Cursor <cursoragent@cursor.com>

Stop waiting on workflow-dispatch completion and post a commit status on PR heads pointing at the dispatched entrypoint run for traceability.

Remove the Vault auto-policy fallback and consolidate ephemeral token minting to a single create-token step with the configured policy. Drop unused ingress-token-policy inputs and ingress pass-through for workflows that never call create-token; client triggers use GITHUB_TOKEN for same-repo entrypoint dispatch. Co-authored-by: Cursor <cursoragent@cursor.com>

Only run the privileged dispatch leg when the completed trigger run originated from pull_request, matching ingress route-pr-ai-menu gating. Co-authored-by: Cursor <cursoragent@cursor.com>

Bring in aw-resolve-apm-assets from main (#1077) while keeping ingress routing: prelude runs only in oblt-aw-ingress and docs-aw-ingress, each gh-aw job is preceded by resolve-apm-assets, and CI validates both models. Co-authored-by: Cursor <cursoragent@cursor.com>

Reconcile with squash-merged #1104 and #1112; keep follow-up ingress permissions and human-readable PR status contexts; drop mistaken client workflows synced into control-plane .github/workflows/. Co-authored-by: Cursor <cursoragent@cursor.com>

Copilot AI review requested due to automatic review settings June 1, 2026 18:07

fr4nc1sc0-r4m0n self-assigned this Jun 1, 2026

Copilot started reviewing on behalf of fr4nc1sc0-r4m0n June 1, 2026 18:07 View session

Copilot AI reviewed Jun 1, 2026

View reviewed changes

Comment thread .github/workflows/oblt-aw-automerge.yml Outdated

Comment thread .github/workflows/oblt-aw-automerge.yml

Comment thread .github/remote-workflow-template/docs/.github/workflows/trigger-docs-aw.yml

Comment thread scripts/oblt_aw_route_specs.py

fr4nc1sc0-r4m0n requested a review from a team June 2, 2026 10:06

fr4nc1sc0-r4m0n and others added 2 commits June 2, 2026 12:26

fix(automerge): restore verify and dependency-collection job gates

6332a87

Re-add if conditions on approve and automerge so they skip when PR validation or dependency collection checks fail. Co-authored-by: Cursor <cursoragent@cursor.com>

feat(client-trigger): fire-and-forget dispatch with PR status link

e1cfd07

Stop waiting on workflow-dispatch completion and post a commit status on PR heads pointing at the dispatched entrypoint run for traceability.

fr4nc1sc0-r4m0n force-pushed the feat/dynamic-routing-v4 branch from 7144888 to e1cfd07 Compare June 2, 2026 10:38

fr4nc1sc0-r4m0n and others added 2 commits June 2, 2026 12:53

Prevent infinite workflow_run re-dispatch in trigger-docs-aw

df69fea

Only run the privileged dispatch leg when the completed trigger run originated from pull_request, matching ingress route-pr-ai-menu gating. Co-authored-by: Cursor <cursoragent@cursor.com>

v1v approved these changes Jun 2, 2026

View reviewed changes

fr4nc1sc0-r4m0n requested a review from theletterf June 2, 2026 12:10

fr4nc1sc0-r4m0n merged commit f64d3c2 into main Jun 2, 2026
24 checks passed

fr4nc1sc0-r4m0n deleted the feat/dynamic-routing-v4 branch June 2, 2026 12:19

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat(workflows): add ingress dynamic routing for obs and docs#1104

feat(workflows): add ingress dynamic routing for obs and docs#1104
fr4nc1sc0-r4m0n merged 6 commits into
mainfrom
feat/dynamic-routing-v4

fr4nc1sc0-r4m0n commented Jun 1, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

fr4nc1sc0-r4m0n commented Jun 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Architecture

Control-plane ingress workflows

Client workflow template (distributed)

Registry and validation

Documentation and agent guidance

Tests

Commits on this branch

Test plan

Risks / rollout

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

fr4nc1sc0-r4m0n commented Jun 1, 2026 •

edited

Loading