Process-guard caller contract¶

This document defines the caller-side trigger requirements for process-guard workflows. Reusable workflows in this repo cannot own their on: triggers — GitHub Actions requires the caller to define them.

Canonical policy: ADR-0012

Why this matters¶

Process guards (branch-name-guard, pr-auto-tracking-issue, spec-discipline) were burning Actions minutes on PRs that didn't need them:

Draft PRs into integration branches (integration/*)
Events that provide no value (edited for branch-name, synchronize for tracking issue)
Stacked runs when multiple pushes happen in quick succession

The fix is a standardized caller pattern: branch filter + minimal event types + concurrency cancel-in-progress.

Required caller pattern¶

For repos with `develop` + `main` (application repos)¶

on:
  pull_request:
    branches: [develop, main]
    types: <see table below>

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

For docs-only repos (`bz-platform-context`)¶

on:
  pull_request:
    branches: [main]
    types: <see table below>

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

Event types per workflow¶

Workflow	`types:`	Notes
`branch-name-guard`	`[opened, reopened, synchronize, ready_for_review]`	`edited` dropped — branch name cannot change on edit.
`pr-auto-tracking-issue`	`[opened, reopened, ready_for_review]`	No `synchronize` — only fires on lifecycle transitions.
`spec-discipline`	`[opened, reopened, synchronize, ready_for_review]`	Needs `synchronize` to re-check changed files.

Complete caller snippets¶

`branch-name-guard.yml`¶

name: Branch name guard

on:
  pull_request:
    branches: [develop, main]
    types: [opened, reopened, synchronize, ready_for_review]

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

permissions:
  contents: read

jobs:
  branch-name:
    uses: aerospace-apps/bz-platform-context/.github/workflows/branch-name-guard-reusable.yml@main

`pr-auto-tracking-issue.yml`¶

name: PR auto-tracking issue

on:
  pull_request:
    branches: [develop, main]
    types: [opened, reopened, ready_for_review]

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

permissions:
  contents: read
  issues: write
  pull-requests: write

jobs:
  auto-track:
    uses: aerospace-apps/bz-platform-context/.github/workflows/pr-auto-tracking-issue-reusable.yml@main
    with:
      project-number: 1
      org: aerospace-apps
    secrets:
      PROJECT_TOKEN: ${{ secrets.PROJECT_TOKEN }}

`spec-discipline.yml`¶

name: Spec Discipline

on:
  pull_request:
    branches: [develop, main]
    types: [opened, reopened, synchronize, ready_for_review]

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

permissions:
  contents: read
  pull-requests: write

jobs:
  discipline:
    uses: aerospace-apps/bz-platform-context/.github/workflows/spec-discipline-reusable.yml@main
    secrets: inherit

What this excludes¶

PRs targeting these branches do not trigger process guards:

integration/* — batch integration branches for grouped testing
feature/* — should not be a PR base anyway
Any other non-canonical branch

The gate for these is the eventual PR from integration/* into develop or main. App-level quality gates (build, test, lint) may run separately via workflow_dispatch.

Migration checklist for sister repos¶

Open the caller workflow file (e.g. .github/workflows/branch-name-guard.yml).
Replace the on: block with the pattern above.
Add the concurrency: block if missing.
Commit and push. Existing PRs will re-trigger with the new filter.

Repos that need updating:

References¶

ADR-0012 — canonical decision
AUTOMATION.md — full automation overview
reservation-api-server#1077 — initial implementation