@postman-cse/onboarding-azure-spec-discovery 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Postman, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,164 @@
+# Postman Onboarding: Azure Spec Discovery
+
+[![CI](https://github.com/postman-cs/postman-azure-spec-discovery-action/actions/workflows/ci.yml/badge.svg)](https://github.com/postman-cs/postman-azure-spec-discovery-action/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/postman-cs/postman-azure-spec-discovery-action?sort=semver)](https://github.com/postman-cs/postman-azure-spec-discovery-action/releases) [![npm](https://img.shields.io/npm/v/%40postman-cse%2Fonboarding-azure-spec-discovery)](https://www.npmjs.com/package/@postman-cse/onboarding-azure-spec-discovery) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+Zero-config discovery and export of API specs from Azure services using only your existing Azure credentials. Use it when a service already runs on Azure and you need a source-of-truth [Spec Hub](https://learning.postman.com/docs/design-apis/specifications/overview/) specification that Postman onboarding can turn into deterministic collections, OpenAPI-backed contract checks, smoke tests, mocks, monitors, repo artifacts, and CI runs.
+
+The action resolves the best specification source for the current repository in this order:
+
+1. **Repo spec** — an OpenAPI/Swagger file already committed to the repository wins outright; Azure is never called.
+2. **Azure API Management (APIM)** — the current HTTP revision of an APIM API, exported as OpenAPI 3.0 JSON through the ARM export protocol.
+3. **App Service API definition** — a site whose `apiDefinition.url` points at a reachable OpenAPI document.
+4. **Local Azure IaC** — OpenAPI content embedded in ARM/Bicep templates or referenced by `azure.yaml` in the repository.
+
+When several Azure candidates match, a four-tier narrowing pipeline (IaC fingerprint, resource-group correlation, `postman:*` tag prefilter, naming heuristic) orders them, and genuinely ambiguous results surface as a ranked GitHub Step Summary table instead of a guess.
+
+## Auth and Postman handoff
+
+The action authenticates with `DefaultAzureCredential` — GitHub OIDC via `azure/login`, environment credentials, or Azure CLI login all work with no extra configuration. It needs only read access (`Reader` plus `API Management Service Reader` covers everything). It never creates, modifies, or deletes Azure resources.
+
+The optional `postman-api-key` / `postman-access-token` inputs exist only to enrich anonymous telemetry with the session account type. They are never used for Azure calls or Postman asset operations.
+
+## Usage
+
+```yaml
+jobs:
+  discover:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - uses: actions/checkout@v4
+      - uses: azure/login@v2
+        with:
+          client-id: ${{ secrets.AZURE_CLIENT_ID }}
+          tenant-id: ${{ secrets.AZURE_TENANT_ID }}
+          subscription-id: ${{ secrets.AZURE_SUBSCRIPTION_ID }}
+      - id: spec
+        uses: postman-cs/postman-azure-spec-discovery-action@v1
+      - run: echo "Resolved ${{ steps.spec.outputs.source-type }} -> ${{ steps.spec.outputs.spec-path }}"
+```
+
+## Examples
+
+### Zero-config resolve-one
+
+```yaml
+- uses: postman-cs/postman-azure-spec-discovery-action@v1
+```
+
+### Known APIM API
+
+```yaml
+- uses: postman-cs/postman-azure-spec-discovery-action@v1
+  with:
+    api-id: /subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.ApiManagement/service/<svc>/apis/<api>
+```
+
+### discover-many mode
+
+```yaml
+- uses: postman-cs/postman-azure-spec-discovery-action@v1
+  with:
+    mode: discover-many
+    resource-group: payments-rg
+```
+
+### Chaining into Postman API onboarding
+
+```yaml
+- id: spec
+  uses: postman-cs/postman-azure-spec-discovery-action@v1
+- uses: postman-cs/postman-api-onboarding-action@v1
+  with:
+    postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+    spec-path: ${{ steps.spec.outputs.spec-path }}
+```
+
+### GitLab and other CI (portable CLI)
+
+```sh
+npx @postman-cse/onboarding-azure-spec-discovery \
+  --subscription-id "$AZURE_SUBSCRIPTION_ID" \
+  --result-json postman-azure-spec-discovery-result.json \
+  --dotenv-path azure-spec.env
+```
+
+The CLI exposes every action input as a `--kebab-case` flag plus CLI-only flags for repo context and discovery tuning (`--repo-root`, `--expected-service-name`, `--dry-run`, `--max-candidates`, and friends). `--help` lists all of them.
+
+## Inputs
+
+<!-- inputs-table:start -->
+| Name | Description | Required | Default |
+| --- | --- | --- | --- |
+| `mode` | Discovery mode: resolve-one selects the single best service for this repository; discover-many exports every exportable candidate. | no | `resolve-one` |
+| `subscription-id` | Optional Azure subscription ID used as the discovery enumeration root. When omitted, the single enabled subscription visible to the credential is used; multiple enabled subscriptions require this input. | no | n/a |
+| `resource-group` | Optional resource group that scopes discovery to one group instead of the whole subscription. | no | n/a |
+| `api-id` | Optional full APIM API ARM resource ID for this service. Use this to bypass broader subscription discovery. | no | n/a |
+| `output-dir` | Directory under the repository root where generated specs are written. | no | `discovered-specs` |
+| `postman-api-key` | Optional service-account PMAK used to mint or re-mint a postman-access-token for telemetry enrichment (account_type). Not used for any Azure or Postman asset operation. | no | n/a |
+| `postman-access-token` | Optional Postman service-account access token, used only to enrich anonymous telemetry with the session account_type. When omitted, postman-api-key alone can mint one for the same purpose. Not used for any Azure or Postman asset operation. | no | n/a |
+<!-- inputs-table:end -->
+
+## Outputs
+
+<!-- outputs-table:start -->
+| Name | Description |
+| --- | --- |
+| `resolution-json` | JSON resolution result describing status, source type, confidence, and evidence. |
+| `resolution-status` | Resolution status: resolved or unresolved. |
+| `source-type` | Resolved source type: repo-spec, apim-export, app-service-api-definition, iac-embedded, manual-review, or discover-many. |
+| `mapping-confidence` | Numeric confidence score for the selected service candidate. |
+| `spec-path` | Path to the resolved or generated specification when available. |
+| `api-id` | Full APIM API ARM resource ID for APIM resolutions; empty for App Service or IaC-local resolutions. |
+| `service-name` | Resolved service name. |
+| `services-json` | discover-many output: JSON array of exported services. |
+| `service-count` | discover-many output: number of exported services. |
+| `export-summary-json` | JSON summary of attempted, exported, failed, and skipped candidates. |
+| `candidates-json` | Ranked ambiguous candidates as JSON when resolution is unresolved with at least two candidates; empty otherwise. |
+| `provider-type` | Provider that produced the resolved spec: apim, app-service, or iac-local. |
+| `spec-format` | Format of the resolved spec: openapi-yaml or openapi-json. |
+| `contract-origin` | Compatibility output; always empty in v1. |
+| `contract-metadata-path` | Compatibility output; always empty in v1. |
+| `variant-count` | Compatibility output; always empty in v1. |
+| `derived-openapi-path` | Path to the derived OpenAPI 3.x document when the source was not already OpenAPI 3.x. |
+| `derived-openapi-version` | OpenAPI version of the derived document: 3.0.3 or 3.1.0. |
+| `derived-openapi-completeness` | Whether the derived OpenAPI document is full or partial. |
+| `derived-openapi-format` | Serialization format of the derived OpenAPI document: openapi-json. |
+| `derived-openapi-evidence-json` | JSON array of evidence strings describing how the derived OpenAPI document was produced. |
+| `narrowing-strategy` | Narrowing tier that produced the candidate ordering: iac-fingerprint, rg-correlation, tag-prefilter, naming-heuristic, or none. |
+<!-- outputs-table:end -->
+
+## Supported providers
+
+| Provider | Source | Exported format |
+| --- | --- | --- |
+| `apim` | Azure API Management current HTTP API revision (ARM export + SAS link) | OpenAPI 3.0 JSON |
+| `app-service` | App Service `siteConfig.apiDefinition.url` document | OpenAPI JSON or YAML |
+| `iac-local` | OpenAPI embedded in repo ARM/Bicep templates or referenced by `azure.yaml` | OpenAPI JSON or YAML |
+
+Non-HTTP APIM API types (SOAP, GraphQL, WebSocket, gRPC, OData) are surfaced as visible-unsupported candidates and routed to manual review; they are never exported in v1. Service- and workspace-scoped APIM APIs are both enumerated. Azure API Center, Functions, Container Apps, and management-group enumeration are out of scope for v1.
+
+## How it works
+
+1. Resolve inputs, repository context, and the target subscription (explicit `subscription-id`, or the single enabled subscription).
+2. Short-circuit to a committed repo spec when one exists.
+3. Probe providers fail-soft: an unauthorized provider is skipped (`skipped:iam`), an erroring one is skipped (`skipped:error`), and discovery continues with the rest.
+4. Enumerate candidates, narrow with the four-tier pipeline, and score against repository signals.
+5. Export the winner (APIM ARM export, guarded HTTPS fetch, or IaC extraction), validate it is real OpenAPI/Swagger with at least one path, and write it under `output-dir` confined to the repository root.
+6. Emit all 22 outputs; ambiguous resolutions additionally render a ranked Step Summary table.
+
+## Resources
+
+- [docs/providers.md](docs/providers.md) — provider contracts and evidence semantics.
+- [docs/LIVE_TESTING_RUNBOOK.md](docs/LIVE_TESTING_RUNBOOK.md) — operator-run live Azure validation.
+- [RELEASE_POLICY.md](RELEASE_POLICY.md), [SECURITY.md](SECURITY.md), [SUPPORT.md](SUPPORT.md).
+
+## Telemetry
+
+The action emits one anonymous `completion` event per run (action name `azure-spec-discovery`) through `@postman-cse/automation-telemetry-core`. The payload never contains Azure subscription, tenant, or resource identifiers, resource names, tags, spec content, URLs, or credentials. Opt out with `POSTMAN_ACTIONS_TELEMETRY=off` or `DO_NOT_TRACK=1`.
+
+## License
+
+[MIT](LICENSE)

package/RELEASE_POLICY.md

@@ -0,0 +1,43 @@
+# Release Policy
+
+## Source of truth
+
+Git tags and GitHub releases are the public release identifiers for this action. `package.json` versions support npm packaging, but consumers should select action versions by Git tag. The committed `dist/` bundle is part of the released artifact because GitHub Actions runs it verbatim from the tag.
+
+## Tag policy
+
+- Immutable releases use `vMAJOR.MINOR.PATCH` tags.
+- The rolling major and minor aliases (`vMAJOR` and `vMAJOR.MINOR`, i.e. `v1` and `v1.0`) are force-moved by the release workflow's `advance-rolling-aliases` job after a successful immutable publish.
+- Existing immutable release tags are never force-pushed or rewritten.
+- Every release tag commit must equal protected `origin/main`; the release workflow verifies this before publication.
+- `v0` tags stay frozen at the last `v0` release.
+- Every immutable release tag has a GitHub release with generated notes.
+
+## Release checks
+
+Run the package validators from this directory before pushing an immutable tag:
+
+1. Confirm the working tree is clean.
+2. `npm test`
+3. `npm run typecheck`
+4. `npm run lint`
+5. `npm run build`
+6. `npm run verify:dist`
+7. `npm run docs:tables` when `action.yml` changes, then confirm the `README.md` tables still match.
+8. Confirm `SECURITY.md`, `SUPPORT.md`, and this file still describe the release surface.
+
+## npm package
+
+The CLI publishes as `@postman-cse/onboarding-azure-spec-discovery` with versions that match the GitHub release tag. Rolling major/minor aliases update action channels and skip npm publishing.
+
+## Compatibility
+
+This action emits `spec-path`, `service-name`, and resolution metadata for downstream actions. Changes to output names, output types, required inputs, or resolution semantics are breaking changes and require a new major release.
+
+## Security fixes
+
+Security fixes ship on the latest immutable `vMAJOR.MINOR.PATCH` tag and move onto the rolling major/minor aliases. Older immutable tags stay published for reproducibility. See [Security Policy](SECURITY.md).
+
+## Suite release order
+
+Azure discovery can be released on its own unless a downstream onboarding example depends on a new composite or bootstrap feature. When multiple onboarding actions change together, release the lower-level actions first, then update the composite action after its pinned dependencies are available.

package/SECURITY.md

@@ -0,0 +1,32 @@
+# Security Policy
+
+## Supported Versions
+
+Only the latest `v1.x.y` release (tracked by rolling major and minor aliases such as `v1` and `v1.0`) receives security fixes. Older tags remain published for reproducibility and are never retroactively modified.
+
+## Reporting a Vulnerability
+
+Please do not open a public issue for security reports.
+
+- Preferred: use GitHub private vulnerability reporting on this repository (Security tab, "Report a vulnerability").
+- Alternative: email [security@postman.com](mailto:security@postman.com) and mention the repository name.
+
+You should receive an acknowledgement within five business days. Please include reproduction steps, the action version tag, and any relevant (redacted) workflow logs.
+
+## Scope Notes
+
+- This action reads Azure credentials from the runner environment and calls read-only Azure ARM APIs. Prefer GitHub OIDC federation via `azure/login` with `id-token: write` and least-privilege Reader roles needed for the providers you use.
+- This action does not require a Postman API key or Postman access token. Postman credentials are consumed by downstream onboarding actions after `spec-path` is resolved.
+- Use `postman-resolve-service-token-action` as the primary way to mint a Postman access token and resolve the team ID from a service-account PMAK.
+- When service-account minting is unavailable, use the Postman CLI credential store created by `postman login` as the fallback source. Do not paste copied cookies, DevTools values, or manually harvested session credentials into workflow secrets.
+- Downstream `credential-preflight` supports `warn` and `enforce` only. Do not document or depend on a public opt-out.
+- Reports about secrets you exposed in your own workflow configuration are out of scope; rotate the credential in Azure or Postman immediately.
+
+## Credential Matrix
+
+| Credential | Used by | Recommended source | Notes |
+| --- | --- | --- | --- |
+| Azure credentials | `azure/login` and this action | GitHub OIDC federated credentials | Grant least-privilege Reader roles for discovery. |
+| `POSTMAN_SERVICE_ACCOUNT_API_KEY` | `postman-resolve-service-token-action` and downstream onboarding actions | GitHub secret | Must be a Postman service-account PMAK when minting an access token. |
+| Postman access token | Downstream onboarding actions | `postman-resolve-service-token-action` output | Pass through `steps.postman_token.outputs.token`; do not store unless your workflow requires it. |
+| Postman team ID | Composite onboarding action | `postman-resolve-service-token-action` output | Pass through `steps.postman_token.outputs.team-id` to the composite action for org-mode handoff. Direct bootstrap workflows should use `workspace-team-id` for workspace creation. |

package/SUPPORT.md

@@ -0,0 +1,30 @@
+# Support
+
+## Before opening an issue
+
+Check the action logs for the selected provider, `resolution-status`, `source-type`, and `mapping-confidence`. The action is read-only against Azure and silently skips providers your role cannot read, so most discovery failures are caused by subscription mismatch, missing RBAC read permissions, missing repo-local specs, or ambiguous service names.
+
+## What to include
+
+- The action version or tag you ran.
+- The `subscription-id` value and provider you expected to resolve.
+- The relevant sanitized workflow step log.
+- The `resolution-json` output with secrets, subscription IDs, and private hostnames redacted.
+- Whether the workflow used azure/login OIDC federation or preconfigured Azure credentials.
+- Whether the result was handed to `postman-api-onboarding-action` or `postman-bootstrap-action`.
+
+Do not include Azure secrets, Postman API keys, Postman access tokens, private OpenAPI documents, or unredacted account identifiers in public issues.
+
+## Common support paths
+
+| Symptom | First check |
+| --- | --- |
+| `Azure credentials are missing or invalid` | Confirm `azure/login` ran first and the federated credential covers this repository and environment. |
+| Provider was skipped | Add the provider's read-only IAM permissions from [docs/providers.md](docs/providers.md#security-and-iam). |
+| `manual-review` result | Provide a repo-local spec, an exact APIM `api-id`, a canonical `postman:repo` tag, or a stronger service-name hint. |
+| Downstream Postman onboarding failed | Check the service-token step outputs and downstream `credential-preflight` setting. Valid values are `warn` and `enforce`. |
+| APIM or App Service API was not selected | Confirm the resource group, API type, current APIM revision, and `siteConfig.apiDefinition.url`; then review [docs/providers.md](docs/providers.md). |
+
+## Security reports
+
+Use [SECURITY.md](SECURITY.md) for vulnerability reports or credential exposure concerns. Do not open a public issue for security-sensitive material.

package/action.yml

@@ -0,0 +1,83 @@
+name: 'Postman Onboarding: Azure Spec Discovery'
+description: Discover Azure-hosted API specs and expose a spec path for Postman onboarding. Part of the Postman API Onboarding suite.
+author: Postman
+branding:
+  icon: cloud
+  color: orange
+inputs:
+  mode:
+    description: 'Discovery mode: resolve-one selects the single best service for this repository; discover-many exports every exportable candidate.'
+    required: false
+    default: resolve-one
+  subscription-id:
+    description: Optional Azure subscription ID used as the discovery enumeration root. When omitted, the single enabled subscription visible to the credential is used; multiple enabled subscriptions require this input.
+    required: false
+    default: ''
+  resource-group:
+    description: Optional resource group that scopes discovery to one group instead of the whole subscription.
+    required: false
+    default: ''
+  api-id:
+    description: Optional full APIM API ARM resource ID for this service. Use this to bypass broader subscription discovery.
+    required: false
+    default: ''
+  output-dir:
+    description: Directory under the repository root where generated specs are written.
+    required: false
+    default: discovered-specs
+  postman-api-key:
+    description: Optional service-account PMAK used to mint or re-mint a postman-access-token for telemetry enrichment (account_type). Not used for any Azure or Postman asset operation.
+    required: false
+    default: ''
+  postman-access-token:
+    description: Optional Postman service-account access token, used only to enrich anonymous telemetry with the session account_type. When omitted, postman-api-key alone can mint one for the same purpose. Not used for any Azure or Postman asset operation.
+    required: false
+    default: ''
+outputs:
+  resolution-json:
+    description: JSON resolution result describing status, source type, confidence, and evidence.
+  resolution-status:
+    description: 'Resolution status: resolved or unresolved.'
+  source-type:
+    description: 'Resolved source type: repo-spec, apim-export, app-service-api-definition, iac-embedded, manual-review, or discover-many.'
+  mapping-confidence:
+    description: Numeric confidence score for the selected service candidate.
+  spec-path:
+    description: Path to the resolved or generated specification when available.
+  api-id:
+    description: Full APIM API ARM resource ID for APIM resolutions; empty for App Service or IaC-local resolutions.
+  service-name:
+    description: Resolved service name.
+  services-json:
+    description: 'discover-many output: JSON array of exported services.'
+  service-count:
+    description: 'discover-many output: number of exported services.'
+  export-summary-json:
+    description: JSON summary of attempted, exported, failed, and skipped candidates.
+  candidates-json:
+    description: Ranked ambiguous candidates as JSON when resolution is unresolved with at least two candidates; empty otherwise.
+  provider-type:
+    description: 'Provider that produced the resolved spec: apim, app-service, or iac-local.'
+  spec-format:
+    description: 'Format of the resolved spec: openapi-yaml or openapi-json.'
+  contract-origin:
+    description: Compatibility output; always empty in v1.
+  contract-metadata-path:
+    description: Compatibility output; always empty in v1.
+  variant-count:
+    description: Compatibility output; always empty in v1.
+  derived-openapi-path:
+    description: Path to the derived OpenAPI 3.x document when the source was not already OpenAPI 3.x.
+  derived-openapi-version:
+    description: 'OpenAPI version of the derived document: 3.0.3 or 3.1.0.'
+  derived-openapi-completeness:
+    description: Whether the derived OpenAPI document is full or partial.
+  derived-openapi-format:
+    description: 'Serialization format of the derived OpenAPI document: openapi-json.'
+  derived-openapi-evidence-json:
+    description: JSON array of evidence strings describing how the derived OpenAPI document was produced.
+  narrowing-strategy:
+    description: 'Narrowing tier that produced the candidate ordering: iac-fingerprint, rg-correlation, tag-prefilter, naming-heuristic, or none.'
+runs:
+  using: node24
+  main: dist/index.cjs