Skip to content

Add report-only flight governance checks (Fixes AB#3827690) - #3364

Open
pedro romero vargas (p3dr0rv) wants to merge 5 commits into
devfrom
feature/flight-governance-checks-3827609
Open

pedro romero vargas (p3dr0rv) wants to merge 5 commits into
devfrom
feature/flight-governance-checks-3827609

Conversation

@p3dr0rv

@p3dr0rv pedro romero vargas (p3dr0rv) commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Summary

Fixes AB#3827690, checkpoint A under PBI 3827609.

Repository flight governance for Common now, reusable by Broker next.
The parent PBI remains open for checkpoint B: approved blocking PR enforcement.

  • New/materially changed flights require an explicit current person/team owner, lifecycle type and same-repository Markdown governance document for every type: Release, Kill Switch and Config, regardless of default.
  • Git authorship is not an ownership fallback; reviewers validate the recorded owner.
  • Add check-pr with explicit PR source/target revisions, merge-base comparison, document-link checks and report-only JSON/Markdown output.
  • Reuse normalized, language-independent rules with a Java adapter; future Kotlin/Authenticator extraction is not implemented here.
  • Integrate a reusable advisory step in Common4j's existing PR job, preserving its tests, coverage and target-dev comparison.

The annotation field remains named premortem for compatibility; it links the governance document for any flight type.

Single-PR initial legacy backfill

The developer explicitly approved this correction so all Common legacy metadata can be reviewed in the existing AzureAD/microsoft-authentication-library-common-for-android#3365, without separate batch/approval PRs.

The checker reads the immutable cutover commit only from the target commit's policy. A missing historical document is recorded as an initial legacy gap only when:

  1. The same declaration/key/default exists without metadata at the frozen pre-policy baseline, PR merge base and current target.
  2. The added owner is explicit, the lifecycle type is supported, and metadata values are resolvable.
  3. The entire change is metadata-only: Java runtime syntax is unchanged after removing governance metadata/imports; other changed files can only be Markdown under docs/.
  4. Reviewers validate owner/type in the same backfill PR.

No per-flight approval list or separate approval PR is needed. PR-authored baseline edits cannot authorize an exemption. New keys, changed defaults, mixed runtime/backfill changes, reclassification and later metadata edits still require documents. A stale branch cannot repeat an initial backfill after the target has acquired metadata or changed its default.

Untouched legacy and formatting/comments remain grandfathered. Broken document links are checked even without an enum edit. Reviewers still identify material behavior changes outside the declarations that static comparisons cannot infer.

Pilot and scope

Policy findings remain advisory in checkpoint A. Missing/ambiguous history, malformed input or incomplete execution return nonzero and cannot appear healthy. Complete JSON is published only after Markdown succeeds; existing output entries are never overwritten.

There are no production-flight/default/provider changes, private-register uploads, live configuration calls, branch-policy changes or Broker adoption here. Checkpoint B requires a representative pilot and administrator approval.

The later developer-invoked monthly audit skill is separate: no scheduled/release pipeline or release gate is added, and monthly auditing does not block repository metadata backfill or PR enforcement.

Validation

JDK 17; from common-java-root:

.\gradlew.bat :flight-governance:test :flight-governance:installDist --console=plain --no-daemon
  • 33 tooling tests passed, no failures/errors/skips; distribution packaging passed.
  • The new initial-backfill case failed under the old approval-list rule before this correction, then passed.
  • Coverage includes all three types, explicit-owner failures, trusted baseline versus forged PR policy, post-cutover/new keys, mixed runtime changes, later metadata edits/stale target branches, broken links, missing/shallow history and malformed source.
  • Previous review regressions for older-branch baseline ancestry, conflicting annotation imports and report-publication failures remain passing.
  • Committed-source replay of all 56 Common annotations against prospective dependency target db4c8d6f8: 56 checked, 0 findings, 52 recorded historical gaps.
  • The same replay against current dev (aea799488) correctly reports 52 missing-document advisories because its trusted cutover policy has not merged yet. This is not represented as a clean current-dev scan.
  • Earlier pipeline YAML/PowerShell syntax/wiring validation remains applicable; this follow-up does not edit pipeline YAML.

Hosted CI for this head and full SDK/lab/device suites are not claimed as locally verified. No credentials or private review registers are included.

Changelog

changelog:none: build tooling, advisory CI and metadata documentation; no SDK behavior/API-shape change.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 23:16
@p3dr0rv pedro romero vargas (p3dr0rv) added the changelog:none No changelog entry or version increment is required. label Nov 19, 2026
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
Successfully started running 6 pipeline(s).
There may be pipelines that require an authorized user to comment /azp run to run.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The baseline ancestry check incorrectly fails valid older-branch PRs, while conflicting annotation imports can bypass metadata checks and Markdown-write failures can leave JSON reports incorrectly marked complete.

3 open issues
What changed in this PR

Adds checkpoint-A, report-only flight governance to the build tooling and Common4j PR pipeline without changing SDK runtime behavior. Enforcement remains a separate checkpoint.

Changes:

  • Adds a language-independent policy engine and Java metadata adapter.
  • Introduces commit-based PR checks, target-trusted migration approvals, and JSON/Markdown reports.
  • Integrates advisory CI reporting and regression tests for policy and Git-history handling.

Review screen: memory-storage/v1
Guidance revision: unknown

File Description
tooling/​flight-governance/​src/​test/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​PrCheckTest.kt Tests committed-source checks, migration trust, history failures, and reporting.
tooling/​flight-governance/​src/​test/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​JavaPolicyAdapterTest.kt Tests metadata extraction and runtime-shape normalization.
tooling/​flight-governance/​src/​test/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​FlightPolicyTest.kt Tests ownership, documentation, grandfathering, and migration rules.
tooling/​flight-governance/​src/​main/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​PrCheck.kt Implements revision comparison, trusted-policy loading, and reports.
tooling/​flight-governance/​src/​main/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​Main.kt Routes check-pr and shares the Git helper.
tooling/​flight-governance/​src/​main/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​JavaPolicyAdapter.kt Converts Java declarations into normalized policy inputs.
tooling/​flight-governance/​src/​main/​kotlin/​com/​microsoft/​identity/​tools/​flightgovernance/​FlightPolicy.kt Evaluates language-independent governance rules.
tooling/​flight-governance/​README.md Documents usage, trust boundaries, and migration approvals.
config/​flight-governance.json Pins the legacy baseline with zero initial approvals.
azure-pipelines/​templates/​steps/​flight-governance.yml Adds reusable scanning and report publication.
azure-pipelines/​pull-request-validation/​common4j.yml Integrates the reporting template into PR validation.

Review effort: Balanced

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

changelog:none No changelog entry or version increment is required.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants