@postman/onboarding-gcp-spec-discovery

Postman Onboarding: GCP Spec Discovery

Discover and export OpenAPI specifications from GCP services for Postman onboarding. The action uses repository context and Google Cloud credentials to select an existing specification or export one from a supported GCP provider.

Authentication

Authenticate with Application Default Credentials (ADC) or Workload Identity Federation. In GitHub Actions, use google-github-actions/auth before this action. project-id is required; location defaults to global.

jobs:
  discover:
    runs-on: ubuntu-latest
    permissions:
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v7
      - uses: google-github-actions/auth@v3
        with:
          workload_identity_provider: ${{ secrets.GCP_WORKLOAD_IDENTITY_PROVIDER }}
          service_account: ${{ secrets.GCP_SERVICE_ACCOUNT }}
      - id: spec
        uses: postman-cs/postman-gcp-spec-discovery-action@v1
        with:
          project-id: my-gcp-project
      - run: echo "Resolved ${{ steps.spec.outputs.source-type }} -> ${{ steps.spec.outputs.spec-path }}"

Usage

Resolve one service

- id: spec
  uses: postman-cs/postman-gcp-spec-discovery-action@v1
  with:
    project-id: my-gcp-project

Discover automatically from the gateway (repository association)

Label the deployed GCP resource that owns this repository's API with postman-repo=<owner--repo> (canonicalized slug: lowercase, / folded to --, invalid characters folded to -; for github.com/acme/payments-api the value is acme--payments-api). The action then resolves the right API from repository identity alone — no api-id, no service-name hints:

- id: spec
  uses: postman-cs/postman-gcp-spec-discovery-action@v1
  with:
    project-id: my-gcp-project
    # repo-slug defaults to the CI-detected repository (GITHUB_REPOSITORY);
    # set it only to resolve on behalf of a different repository.

Exactly one conflict-free exact label match auto-selects. Zero matches, multiple matches, or colliding label values stay unresolved (manual-review) with the expected label value printed in the evidence — the action never guesses. Colliding repositories (same canonical value, e.g. case-fold or punctuation collisions, or slugs longer than 63 characters) must set api-id or expected-api-ids-json explicitly.

postman-repo is an owner assertion, not a verified binding: anyone with *.update on the resource can point it at any repository. Keep IAM label-write privileges scoped to the deployment pipeline; ambiguity still always forces manual-review.

A ready-to-distribute per-service-repo workflow using this pattern (adapted from the AWS discovery-hub pattern, but hub-less — each repo discovers its own spec) ships in templates/postman-gcp-onboard.yml. See docs/repository-association.md for marker placement per provider, ambiguity semantics, and WIF bootstrap.

Resolve a known config or Apigee proxy revision

- uses: postman-cs/postman-gcp-spec-discovery-action@v1
  with:
    project-id: my-gcp-project
    api-id: projects/my-gcp-project/locations/global/apis/payments/configs/v1

Export every candidate

- uses: postman-cs/postman-gcp-spec-discovery-action@v1
  with:
    project-id: my-gcp-project
    mode: discover-many

Portable CLI

npx @postman/onboarding-gcp-spec-discovery \
  --project-id "$GCP_PROJECT_ID" \
  --result-json postman-gcp-spec-discovery-result.json \
  --dotenv-path gcp-spec.env

Inputs

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
project-id	Google Cloud project ID used as the exact discovery and credential preflight scope.	yes	n/a
location	Google Cloud API Gateway location. v1 supports global.	no	global
api-id	Optional full API Gateway config, Cloud Endpoints config, Apigee proxy revision, Apigee archive deployment, API Hub spec, legacy Apigee Registry spec, Apigee portal apidoc, Vertex extension, Dialogflow tool, or CES tool/toolset resource name. Use this to bypass broader project discovery.	no	n/a
repo-slug	Repository slug (owner/name) used for repository-association matching against postman-repo resource labels. Defaults to the CI-detected repository (GITHUB_REPOSITORY).	no	n/a
expected-service-name	Optional expected service name used as a ranking hint and as the reported service name when resolution stays manual-review.	no	n/a
expected-api-ids-json	Optional JSON array of full resource names that this repository expects to own; exact matches rank highest during resolution.	no	[]
service-mapping-json	Optional JSON object mapping resource names to service names, used to name exported specs for label-incapable providers.	no	{}
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 GCP 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 GCP or Postman asset operation.	no	n/a

Outputs

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, api-gateway-config, cloud-endpoints-config, apigee-proxy, apigee-archive-deployment, api-hub-spec, api-hub-boosted-spec, api-hub-gateway-openapi-spec, apigee-registry-spec, app-integration-trigger, connectors-custom-spec, apigee-portal-doc, vertex-extension-manifest, dialogflow-tool-schema, ces-tool-schema, ces-toolset-schema, 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.
spec-files-json	Optional JSON inventory of the authoritative multi-file definition set (schemaVersion 1). Empty for single-file, unresolved, and discover-many results.
api-id	Full resource name of the exported cloud source (API Gateway config, Cloud Endpoints config, Apigee proxy revision, Apigee archive deployment, API Hub spec, legacy Apigee Registry spec, Apigee portal apidoc, Vertex extension, Dialogflow tool, or CES tool/toolset); empty for repo, generated, 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: api-gateway, cloud-endpoints, apigee, api-hub, apigee-registry, app-integration, connectors-custom, apigee-portal, vertex-extensions, dialogflow-tools, ces-toolsets, or iac-local.
spec-format	Format of the resolved spec: openapi-yaml, openapi-json, asyncapi-yaml, asyncapi-json, graphql-sdl, graphql-introspection-json, protobuf, wsdl, or mcp-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, project-correlation, label-prefilter, naming-heuristic, or none.

Supported providers

Provider	Source type	Exported format
api-gateway	api-gateway-config	OpenAPI from the full API Gateway config openapiDocuments payload
cloud-endpoints	cloud-endpoints-config	OpenAPI from Cloud Endpoints sourceInfo OPEN_API_* sources
apigee	apigee-proxy / apigee-archive-deployment	OpenAPI from an Apigee proxy revision zip under resources/oas or resources/openapi, or exactly one OpenAPI document in an environment archive deployment original zip
api-hub	api-hub-spec / api-hub-boosted-spec / api-hub-gateway-openapi-spec	Verbatim OpenAPI via specs:contents, plus distinct Google-generated additional content from fetchAdditionalSpecContent when available
apigee-registry	apigee-registry-spec	Legacy Apigee Registry specs:getContents for existing customer data only (no-longer-supported; not a replacement for API Hub)
app-integration	app-integration-trigger	OpenAPI 3.0 generated server-side by Application Integration generateOpenApiSpec for published integrations with API triggers
connectors-custom	connectors-custom-spec	The OpenAPI document a custom Integration Connector was built from, fetched from its recorded gs:// specLocation
apigee-portal	apigee-portal-doc	Original OpenAPI documentation published through an Apigee portal API document
vertex-extensions	vertex-extension-manifest	Inline or Cloud Storage OpenAPI from a Vertex AI extension manifest
dialogflow-tools	dialogflow-tool-schema	Original OpenAPI text schema stored on a Dialogflow CX tool
ces-toolsets	ces-tool-schema / ces-toolset-schema	Original OpenAPI schemas from standalone Conversational Agents app tools and toolset-scoped tools
iac-local	iac-embedded / path reference	OpenAPI referenced by local Terraform google_api_gateway_api_config or google_endpoints_service resources

The resolver probes providers in this order: api-gateway, cloud-endpoints, apigee, api-hub, apigee-registry, app-integration, connectors-custom, apigee-portal, vertex-extensions, dialogflow-tools, ces-toolsets, iac-local. A committed repo-spec wins before remote discovery. Candidates are narrowed by iac-fingerprint, project-correlation, label-prefilter, then naming-heuristic; the postman-repo label is an ownership signal. Ambiguous or unsupported results are reported for manual review rather than guessed. Agent Engine class methods are runtime metadata and are not probed as OpenAPI sources.

v1 boundaries

v1 does not probe Cloud Run, GKE, or Functions runtime URLs (there is no GCP catalog of runtime specs), does not fetch arbitrary remote URLs, does not synthesize routes from traffic observations (APIM shadow-API discovery yields operations, not contracts), and does not convert gRPC or google.api.Service definitions to OpenAPI. Non-OpenAPI API Hub spec types (proto, WSDL, MCP) surface as manual review candidates rather than being converted.

How it works

• Validate project-id and Google credentials.
• Prefer a committed repository specification.
• Probe supported providers fail-soft and collect candidates.
• Narrow and rank candidates using repository and project signals.
• Export and validate the selected OpenAPI document inside output-dir.
• Emit resolution, export, candidate, and narrowing outputs.

Resources

• Provider contracts
• Repository association
• Per-service-repo onboarding workflow template
• Live testing runbook
• RELEASE_POLICY.md, SECURITY.md, SUPPORT.md

Telemetry

The action emits one anonymous completion event per run (action name gcp-spec-discovery) through @postman-cse/automation-core. The payload excludes project identifiers, resource names, labels, specification content, URLs, and credentials. Opt out with POSTMAN_ACTIONS_TELEMETRY=off or DO_NOT_TRACK=1.

License

MIT