Skip to content

ADR-0012: Process-guard caller triggers

Status: Accepted Date: 2026-09-25 Deciders: Platform engineering Impacted Repos: bz-platform-context, reservation-api-server, admin-web-app, venuplus-app, customer-web-app, all future repos consuming reusable workflows

Context

Process-guard workflows (branch-name-guard, pr-auto-tracking-issue, spec-discipline) run on every PR event by default. When ~30 draft PRs targeted an integration branch (integration/test-coverage) for batch testing, each synchronize or edited event burned Actions minutes unnecessarily — the guards only matter for PRs headed to canonical integration (develop) or release (main) branches.

GitHub's reusable workflows cannot own on: triggers; the caller in each consumer repo defines when the workflow fires. This means:

  1. Trigger policy must be documented centrally.
  2. Callers must copy the correct on: block; the reusable cannot enforce it.
  3. Existing callers (including this repo's self-hosting callers) burn minutes on events that provide no value.

reservation-api-server#1077 implemented the fix for that repo. This ADR encodes the policy so sister repos can align without re-discovering the rationale.

Decision

1. Branch filter on callers

Process-guard callers MUST restrict to PRs targeting the repo's integration and release base branches:

on:
  pull_request:
    branches: [develop, main]   # or just [main] for docs-only repos

This excludes PRs into integration/*, feature/*, or other batch/experiment branches from process-guard CI.

2. Event types per workflow

Workflow Required types: Rationale
branch-name-guard [opened, reopened, synchronize, ready_for_review] Branch name cannot change on edited; drop it.
pr-auto-tracking-issue [opened, reopened, ready_for_review] Only needs to run once per PR lifecycle transition, not on every push.
spec-discipline [opened, reopened, synchronize, ready_for_review] Checks spec content; needs synchronize for file changes.

3. Concurrency with cancel-in-progress

Callers MUST set a concurrency group keyed by PR number (or SHA for push triggers) with cancel-in-progress: true:

concurrency:
  group: ${{ github.workflow }}-${{ github.event.pull_request.number || github.sha }}
  cancel-in-progress: true

This ensures a new push cancels any in-flight run for the same PR, avoiding stacked runs.

4. Integration/feature-batch branches

PRs into integration/* or other batch branches: - Do NOT trigger automatic process-guard CI. - The gate is the eventual PR from integration/* into develop or main. - App-level quality gates (build, test, lint) may use workflow_dispatch for on-demand validation of the integration branch.

5. Reusable workflows stay in bz-platform-context

The reusable workflow bodies remain in this repo under .github/workflows/*-reusable.yml. Callers in consumer repos invoke them with uses: aerospace-apps/bz-platform-context/.github/workflows/<name>-reusable.yml@main.

Triggers stay in consumers because GitHub does not allow reusable workflows to define their own on: blocks.

Consequences

Positive

  • Draft PRs into integration branches no longer burn CI minutes.
  • Clear contract: callers copy a documented snippet rather than guessing.
  • cancel-in-progress prevents stacked runs on rapid pushes.

Negative / Trade-offs

  • Sister repos must patch their callers; not automatic.
  • Slight risk that a repo forgets to update and keeps burning minutes until someone notices.

Risks / Mitigations

  • Risk: A repo omits the branch filter and burns minutes. Mitigation: Document the pattern in docs/PROCESS-GUARD-CALLERS.md; link from AUTOMATION.md. Optionally add a CI check in this repo that lints caller snippets in sister repos (future enhancement).

Alternatives Considered

  • Central reusable owns triggers: Rejected — GitHub Actions does not support on: in reusable workflows.
  • No branch filter, just concurrency: Rejected — still fires jobs on every event for non-canonical branches.
  • Disable process guards entirely for draft PRs: Rejected — draft PRs into develop/main should still be validated when un-drafted.

Implementation Notes

Artifact Change
This ADR Canonical policy
docs/PROCESS-GUARD-CALLERS.md Caller contract doc with copy-paste YAML
AUTOMATION.md Link to the new doc
.github/workflows/branch-name-guard.yml (this repo) Align to pattern
.github/workflows/pr-auto-tracking-issue.yml (this repo) Align to pattern
Sister repo callers Owners update per the doc

References