@postman-cse/onboarding-insights

Postman Onboarding: Insights Linking

Links Postman Insights discovered services to API Catalog workspaces and git repositories after deployment, so every service the Insights agent finds lands in your catalog with a collection, a repo link, and live telemetry.

Part of the Postman API Onboarding suite.

Prerequisites

• The Postman Insights DaemonSet agent must already be running on your cluster in discovery mode.
• The target service must already be deployed, running, and receiving enough traffic for the agent to discover it.
• A Postman workspace and environment must already exist for the service.
• A Postman service account API key must be available as a CI secret. Use postman-resolve-service-token-action to mint the postman-access-token and postman-team-id at runtime.
• Choose the Postman data residency region up front with postman-region (us or eu).

This action does not deploy the Insights agent, create workspaces, create environments, upload OpenAPI specs, or sync repo artifacts. It only links a service that Insights has already discovered.

Credential requirement for the Insights linking steps. The service discovery and git-link calls run on Postman's api-catalog service and accept a service-account access token. The Insights acknowledgment and application-binding steps run on the akita (Insights) service, which authenticates against a Postman user identity and answers 401 "Postman User not found" for a service-account token. To complete the full link, supply a credential pair that carries a Postman user identity (a user's access token and user PMAK). A service-account-only pair from postman-resolve-service-token-action is sufficient for discovery and git linking but cannot finish the Insights acknowledgment.

Which action should I use?

Need	Action
Mint a service-account access token and team ID	Postman Onboarding: Service Token
Run the full workspace, collection, repo sync, and optional Insights pipeline	Postman API Onboarding
Create a workspace, upload an OpenAPI spec, and generate collections	Postman Onboarding: Workspace Bootstrap
Sync Postman artifacts, mocks, monitors, and CI files back to the repo	Postman Onboarding: Repo Sync
Link an already discovered Insights service to an existing workspace	Postman Onboarding: Insights Linking
Discover OpenAPI specs from AWS services	Postman Onboarding: AWS Spec Discovery
Apply a curated smoke flow to an existing Smoke collection	Postman Onboarding: Smoke Flow

Usage

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # ... deploy your service to Kubernetes ...

      - id: postman_token
        uses: postman-cs/postman-resolve-service-token-action@v2
        with:
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-region: us

      - uses: postman-cs/postman-insights-onboarding-action@v2
        with:
          project-name: core-payments
          workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
          environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman_token.outputs.token }}
          postman-team-id: ${{ steps.postman_token.outputs.team-id }}

Examples

Standalone after a Kubernetes deploy

jobs:
  deploy:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      # ... deploy your service to Kubernetes ...

      - id: postman_token
        uses: postman-cs/postman-resolve-service-token-action@v2
        with:
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-region: us

      - uses: postman-cs/postman-insights-onboarding-action@v2
        with:
          project-name: core-payments
          workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
          environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
          cluster-name: my-cluster
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman_token.outputs.token }}
          postman-team-id: ${{ steps.postman_token.outputs.team-id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}
          poll-timeout-seconds: 180

Full onboarding pipeline

jobs:
  provision:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v5

      - id: postman_token
        uses: postman-cs/postman-resolve-service-token-action@v2
        with:
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-region: us

      - uses: postman-cs/postman-bootstrap-action@v2
        id: bootstrap
        with:
          project-name: core-payments
          spec-url: https://raw.githubusercontent.com/postman-cs/postman-insights-onboarding-action/main/examples/core-payments-openapi.yaml
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman_token.outputs.token }}

      # ... deploy service to Kubernetes ...

      - uses: postman-cs/postman-repo-sync-action@v2
        id: sync
        with:
          project-name: core-payments
          workspace-id: ${{ steps.bootstrap.outputs.workspace-id }}
          baseline-collection-id: ${{ steps.bootstrap.outputs.baseline-collection-id }}
          smoke-collection-id: ${{ steps.bootstrap.outputs.smoke-collection-id }}
          contract-collection-id: ${{ steps.bootstrap.outputs.contract-collection-id }}
          environments-json: '["prod"]'
          env-runtime-urls-json: '{"prod":"https://api.example.com"}'
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman_token.outputs.token }}

      - uses: postman-cs/postman-insights-onboarding-action@v2
        with:
          project-name: core-payments
          workspace-id: ${{ steps.bootstrap.outputs.workspace-id }}
          environment-id: ${{ fromJSON(steps.sync.outputs.environment-uids-json).prod }}
          cluster-name: my-cluster
          postman-region: us
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          postman-access-token: ${{ steps.postman_token.outputs.token }}
          postman-team-id: ${{ steps.postman_token.outputs.team-id }}
          github-token: ${{ secrets.GITHUB_TOKEN }}

Tuning discovery polling

The Insights agent takes time to discover services after pods start. The action polls the API Catalog discovered-services list until the service appears or the timeout is reached. For services that take longer to appear (cold cluster, large pod startup time), raise the timeout:

      - uses: postman-cs/postman-insights-onboarding-action@v2
        with:
          project-name: core-payments
          workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
          environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
          postman-region: us
          postman-access-token: ${{ steps.postman_token.outputs.token }}
          poll-timeout-seconds: 300
          poll-interval-seconds: 15

poll-timeout-seconds is clamped to 10-600 and poll-interval-seconds to 2-60. If the service never appears within the timeout, the action sets status to not-found and emits a warning without failing the workflow.

Credential preflight modes

Before any onboarding write, the action can verify that postman-api-key and postman-access-token resolve to the same parent organization. The default warn mode logs a note and continues. Set credential-preflight to enforce to fail fast on mismatched credentials:

      - uses: postman-cs/postman-insights-onboarding-action@v2
        with:
          project-name: core-payments
          workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
          environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
          postman-access-token: ${{ steps.postman_token.outputs.token }}
          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
          credential-preflight: enforce

See Credentials and Identity for the full policy, API key auto-creation behavior, and how to obtain the access token.

Non-GitHub CI via the CLI

The same logic ships as a CLI (postman-insights-onboard) for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems:

npm install -g @postman-cse/onboarding-insights
postman-insights-onboard \
  --project-name core-payments \
  --workspace-id ws_123 \
  --environment-id env_123 \
  --postman-access-token "$POSTMAN_ACCESS_TOKEN" \
  --postman-team-id "$POSTMAN_TEAM_ID" \
  --postman-api-key "$POSTMAN_API_KEY" \
  --postman-region us \
  --cluster-name my-cluster

See CLI Usage for provider auto-detection, output formats, and GitLab/Bitbucket/Azure pipeline examples.

Inputs

Name	Description	Required	Default
project-name	Service name or Jira/Xray project key to match against the final discovered-service segment	Yes
workspace-id	Postman workspace ID to link the discovered service to	Yes
environment-id	Postman environment UID for the onboarding association	Yes
system-environment-id	Postman system environment UUID for service-level Insights acknowledgment	No
cluster-name	Insights cluster name. When set, matches {cluster-name}/{project-name} exactly in discovered services	No
repo-url	Repository URL for Git onboarding. Auto-detected from CI context when omitted.	No
postman-access-token	Postman access token (x-access-token) for the Bifrost linking calls. The api-catalog discovery and git-link steps accept a service-account token (mint it with postman-resolve-service-token-action); the Insights (akita) acknowledgment and application-binding steps require a token carrying a Postman user identity — a service-account token answers 401 "Postman User not found" there.	Yes
postman-team-id	Explicit Postman team ID for org-mode integration request headers. When omitted, x-entity-team-id is not sent.	No
github-token	Optional GitHub token passed as git_api_key when repository auth is required by onboarding/git	No
postman-api-key	Service-account Postman API key (PMAK-*) for the application binding call. Auto-created from postman-access-token when omitted or invalid after a clear 401/403 validation failure.	No
credential-preflight	Credential identity preflight policy. warn (default) logs a note and continues when postman-api-key and postman-access-token resolve to different parent orgs; enforce fails the run on that condition before any onboarding write. Supported values are warn and enforce.	No	warn
poll-timeout-seconds	Maximum seconds to wait for the service to appear in the discovered list	No	120
poll-interval-seconds	Seconds between discovery polling attempts	No	10
postman-region	Postman data residency region for public API calls. One of: us or eu.	No	us

Supply postman-team-id only for org-mode tokens that require an explicit team header. For non-org tokens, leave it unset so Postman can infer team context from the access token. Credential details, the preflight policy, and API key auto-creation are documented in Credentials and Identity.

Outputs

Name	Description	Required	Default
discovered-service-id	Numeric ID from the API Catalog discovered-services list
discovered-service-name	Full cluster/service name of the discovered service
collection-id	Collection ID returned by the prepare-collection step
application-id	Insights application binding ID from the observability API
verification-token	Insights team verification token (tvt_*) for DaemonSet telemetry
status	Onboarding result: success, not-found, or error

Failures set status=error before the action exits.

How it works

Discovery poll. The action polls the API Catalog discovered-services list at the configured interval until a service matching {cluster-name}/{project-name} appears (suffix matching when cluster-name is omitted) or the timeout is reached.

Catalog prep. It then calls POST /api/v1/onboarding/prepare-collection to create the API Catalog collection entry for the discovered service in your workspace.

Git link. POST /api/v1/onboarding/git with via_integrations: false links the service to the GitHub repository (repo-url input, auto-detected from CI context when omitted; github-token is passed as git_api_key only when the endpoint requires repository auth). Postman's connect code docs cover the product workflow this binding supports.

Acknowledgment. The action resolves the svc_* Akita service ID, marks the service as managed (POST /v2/api-catalog/services/onboard), and acknowledges the workspace (POST /v2/workspaces/{id}/onboarding/acknowledge) to activate the Insights project.

Binding. Finally it creates an application binding with the observability API, which is required for service graph edge generation, and retrieves the team verification token (tvt_*) for DaemonSet telemetry.

For local builds, contract smoke monitoring, and release channels, see Development and Operations.

Resources

The suite

Action	Role
Postman API Onboarding	Entry point: chains workspace bootstrap, repo sync, and optional Insights linking
Postman Onboarding: Service Token	Mints the service-account access token and team ID
Postman Onboarding: AWS Spec Discovery	Discovers and exports API specs from AWS services
Postman Onboarding: Workspace Bootstrap	Creates the workspace, uploads the spec, generates collections
Postman Onboarding: Smoke Flow	Applies a curated flow.yaml to the Smoke collection
Postman Onboarding: Repo Sync	Exports artifacts into the repo and wires CI, mocks, and monitors
Postman Onboarding: Insights Linking	Links Insights discovered services to the workspace

• postman-resolve-service-token-action: mints a service-account access token and team ID.
• postman-api-onboarding-action: composite action that orchestrates the onboarding pipeline.
• postman-bootstrap-action: workspace provisioning, spec upload, and collection generation.
• postman-smoke-flow-action: applies a curated flow.yaml to the canonical Smoke collection.
• postman-repo-sync-action: artifact sync, environments, mocks, monitors, and CI templates.
• postman-aws-spec-discovery-action: discovers API specs from AWS.
• npm package: @postman-cse/onboarding-insights
• Postman Learning Center: Insights overview, connect Insights, Insights API Catalog agent reference, API Catalog overview, connect code
• Credentials and Identity
• Development and Operations
• Support
• Security Policy
• Release Policy

Telemetry

This action sends a single non-identifying usage event when a run completes, so the Postman team can measure adoption across CI systems. The event contains the action name and version, your Postman team ID, the detected CI provider and runner kind, the run outcome, the CI run identifier, an event timestamp, and a one-way SHA-256 hash of the repository identifier. Each event also carries a schema version and a constant event marker (always completion). The Postman team ID is sent in the clear on a legitimate-interest basis to measure product adoption.

The events.pm-cse.dev endpoint is operated by the Postman Customer Success Engineering team. Postman, Inc. processes these events only to measure onboarding adoption in aggregate, retains them only as aggregated counts for product-adoption trend analysis, and includes no payload field that identifies an individual person.

It never sends API keys, access tokens, spec content, workspace or repository names, or any personal data. It is fire-and-forget with a hard timeout and can never block or fail your pipeline. Corporate HTTP and HTTPS proxies are honored through the standard HTTPS_PROXY, HTTP_PROXY, and NO_PROXY environment variables.

Disable it by setting either environment variable in your CI:

POSTMAN_ACTIONS_TELEMETRY=off
# or the cross-tool standard
DO_NOT_TRACK=1

Telemetry is also skipped automatically when no Postman team ID can be resolved.

A run that ends in the not-found state (no matching Insights project) is recorded with a failure outcome.

Events are sent over HTTPS to https://events.pm-cse.dev/v1/events. To allowlist this destination on a restricted network, or to route events to a collector you operate, set the POSTMAN_ACTIONS_TELEMETRY_ENDPOINT environment variable to your own URL.

License

MIT