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-cse/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

1. Validate project-id and Google credentials.
2. Prefer a committed repository specification.
3. Probe supported providers fail-soft and collect candidates.
4. Narrow and rank candidates using repository and project signals.
5. Export and validate the selected OpenAPI document inside output-dir.
6. 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