@postman-cse/onboarding-insights 1.0.2 → 1.0.3

package/README.md

@@ -2,10 +2,32 @@
 
 [![CI](https://github.com/postman-cs/postman-insights-onboarding-action/actions/workflows/ci.yml/badge.svg)](https://github.com/postman-cs/postman-insights-onboarding-action/actions/workflows/ci.yml) [![Release](https://img.shields.io/github/v/release/postman-cs/postman-insights-onboarding-action?sort=semver)](https://github.com/postman-cs/postman-insights-onboarding-action/releases) [![npm](https://img.shields.io/npm/v/%40postman-cse%2Fonboarding-insights)](https://www.npmjs.com/package/@postman-cse/onboarding-insights) [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
-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.
+Links [Postman Insights](https://learning.postman.com/docs/insights/overview/) discovered services to [API Catalog](https://learning.postman.com/docs/api-catalog/overview/) 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](https://github.com/postman-cs/postman-api-onboarding-action).
 
+## Prerequisites
+
+- The [Postman Insights DaemonSet agent](https://learning.postman.com/docs/api-catalog/connect/insights/) 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](https://learning.postman.com/docs/collaborating-in-postman/using-workspaces/overview/) and environment must already exist for the service.
+- A [Postman service account](https://learning.postman.com/docs/administration/service-accounts/) API key must be available as a CI secret. Use [postman-resolve-service-token-action](https://github.com/postman-cs/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.
+
+## Which action should I use?
+
+| Need | Action |
+| --- | --- |
+| Mint a service-account access token and team ID | [Postman Onboarding: Service Token](https://github.com/postman-cs/postman-resolve-service-token-action) |
+| Run the full workspace, collection, repo sync, and optional Insights pipeline | [Postman API Onboarding](https://github.com/postman-cs/postman-api-onboarding-action) |
+| Create a workspace, upload an OpenAPI spec, and generate collections | [Postman Onboarding: Workspace Bootstrap](https://github.com/postman-cs/postman-bootstrap-action) |
+| Sync Postman artifacts, mocks, monitors, and CI files back to the repo | [Postman Onboarding: Repo Sync](https://github.com/postman-cs/postman-repo-sync-action) |
+| Link an already discovered Insights service to an existing workspace | [Postman Onboarding: Insights Linking](https://github.com/postman-cs/postman-insights-onboarding-action) |
+| Discover OpenAPI specs from AWS services | [Postman Onboarding: AWS Spec Discovery](https://github.com/postman-cs/postman-aws-spec-discovery-action) |
+| Apply a curated smoke flow to an existing Smoke collection | [Postman Onboarding: Smoke Flow](https://github.com/postman-cs/postman-smoke-flow-action) |
+
 ## Usage
 
 ```yaml
@@ -17,23 +39,23 @@ jobs:
 
       # ... deploy your service to Kubernetes ...
 
+      - id: postman_token
+        uses: postman-cs/postman-resolve-service-token-action@v1
+        with:
+          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+          postman-region: us
+
       - uses: postman-cs/postman-insights-onboarding-action@v1
         with:
-          project-name: af-cards-activation
+          project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
           environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
-          postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          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 }}
 ```
 
-### Prerequisites
-
-- The Postman Insights DaemonSet agent must be running on your cluster in discovery mode.
-- The target service must be deployed and running (the agent discovers it from live traffic).
-- A Postman workspace and environment must already exist for the service.
-- A `postman-access-token` (session token) is required for Bifrost API access. See [Credentials and Identity](docs/credentials.md).
-
-This action does **not** deploy the Insights agent, create workspaces, or manage environments. Use [postman-bootstrap-action](https://github.com/postman-cs/postman-bootstrap-action) and [postman-repo-sync-action](https://github.com/postman-cs/postman-repo-sync-action) for those concerns.
-
 ## Examples
 
 ### Standalone after a Kubernetes deploy
@@ -47,14 +69,22 @@ jobs:
 
       # ... deploy your service to Kubernetes ...
 
+      - id: postman_token
+        uses: postman-cs/postman-resolve-service-token-action@v1
+        with:
+          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+          postman-region: us
+
       - uses: postman-cs/postman-insights-onboarding-action@v1
         with:
-          project-name: af-cards-activation
-          workspace-id: ${{ steps.bootstrap.outputs.workspace-id }}
-          environment-id: ${{ steps.sync.outputs.environment-uids-json && fromJSON(steps.sync.outputs.environment-uids-json).prod }}
+          project-name: core-payments
+          workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
+          environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
           cluster-name: my-cluster
-          postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          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
 ```
@@ -68,51 +98,62 @@ jobs:
     steps:
       - uses: actions/checkout@v5
 
+      - id: postman_token
+        uses: postman-cs/postman-resolve-service-token-action@v1
+        with:
+          postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
+          postman-region: us
+
       - uses: postman-cs/postman-bootstrap-action@v1
         id: bootstrap
         with:
-          project-name: af-cards-activation
-          spec-url: https://example.com/openapi.yaml
+          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: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          postman-access-token: ${{ steps.postman_token.outputs.token }}
 
       # ... deploy service to Kubernetes ...
 
       - uses: postman-cs/postman-repo-sync-action@v1
         id: sync
         with:
-          project-name: af-cards-activation
+          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: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          postman-access-token: ${{ steps.postman_token.outputs.token }}
 
       - uses: postman-cs/postman-insights-onboarding-action@v1
         with:
-          project-name: af-cards-activation
+          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-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          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:
+The Insights agent takes time to discover services after pods start. The action polls the [API Catalog](https://learning.postman.com/docs/api-catalog/connect/insights/) 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:
 
 ```yaml
       - uses: postman-cs/postman-insights-onboarding-action@v1
         with:
-          project-name: af-cards-activation
+          project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
           environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
-          postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          postman-region: us
+          postman-access-token: ${{ steps.postman_token.outputs.token }}
           poll-timeout-seconds: 300
           poll-interval-seconds: 15
 ```
@@ -121,15 +162,15 @@ The Insights agent takes time to discover services after pods start. The action
 
 ### 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. Set `credential-preflight` to `enforce` to fail fast on mismatched credentials, or `off` to skip the probes (the default `warn` logs and continues):
+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:
 
 ```yaml
       - uses: postman-cs/postman-insights-onboarding-action@v1
         with:
-          project-name: af-cards-activation
+          project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
           environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
-          postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
+          postman-access-token: ${{ steps.postman_token.outputs.token }}
           postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
           credential-preflight: enforce
 ```
@@ -143,10 +184,13 @@ The same logic ships as a CLI (`postman-insights-onboard`) for GitLab CI, Bitbuc
 ```bash
 npm install -g @postman-cse/onboarding-insights
 postman-insights-onboard \
-  --project-name af-cards-activation \
+  --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
 ```
 
@@ -163,16 +207,17 @@ See [CLI Usage](docs/cli.md) for provider auto-detection, output formats, and Gi
 | `system-environment-id` | Postman system environment UUID for service-level Insights acknowledgment | No |  |
 | `cluster-name` | Insights cluster name. Matches {cluster}/{project-name} 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 for Bifrost API calls | Yes |  |
-| `postman-team-id` | Explicit Postman team ID for org-mode Bifrost request headers. When omitted, x-entity-team-id is not sent. | No |  |
+| `postman-access-token` | Service-account Postman access token for integration API calls. Prefer minting it with postman-resolve-service-token-action. | 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` | 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; off skips the identity probes entirely (the reactive error guidance still applies). A rejected or auto-created postman-api-key is never failed on. | No | `warn` |
+| `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` |
 <!-- inputs-table:end -->
 
-Supply `postman-team-id` only for org-mode tokens that require an explicit team header. For non-org tokens, leave it unset so Bifrost can infer team context from the access token. Credential details, the preflight policy, and API key auto-creation are documented in [Credentials and Identity](docs/credentials.md).
+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](docs/credentials.md).
 
 ## Outputs
 
@@ -191,15 +236,15 @@ Failures set `status=error` before the action exits.
 
 ## How it works
 
-**Discovery poll.** The action polls the API Catalog discovered-services list (`GET /api/v1/onboarding/discovered-services?status=discovered` on Bifrost api-catalog) 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.
+**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).
+**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](https://learning.postman.com/docs/api-catalog/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 (`POST /v2/agent/api-catalog/workspaces/{id}/applications`, sent directly to `api.observability.postman.com` rather than through Bifrost), which is required for service graph edge generation, and retrieves the team verification token (`tvt_*`) for DaemonSet telemetry.
+**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](docs/development.md).
 
@@ -224,7 +269,52 @@ For local builds, contract smoke monitoring, and release channels, see [Developm
 - [postman-repo-sync-action](https://github.com/postman-cs/postman-repo-sync-action): artifact sync, environments, mocks, monitors, and CI templates.
 - [postman-aws-spec-discovery-action](https://github.com/postman-cs/postman-aws-spec-discovery-action): discovers API specs from AWS.
 - npm package: [@postman-cse/onboarding-insights](https://www.npmjs.com/package/@postman-cse/onboarding-insights)
-- [Postman Insights documentation](https://learning.postman.com/docs/insights/insights-overview/)
+- Postman Learning Center: [Insights overview](https://learning.postman.com/docs/insights/overview/), [connect Insights](https://learning.postman.com/docs/api-catalog/connect/insights/), [Insights API Catalog agent reference](https://learning.postman.com/docs/insights/reference/agent/api-catalog/), [API Catalog overview](https://learning.postman.com/docs/api-catalog/overview/), [connect code](https://learning.postman.com/docs/api-catalog/connect/code/)
+- [Credentials and Identity](docs/credentials.md)
+- [Development and Operations](docs/development.md)
+- [Support](SUPPORT.md)
+- [Security Policy](SECURITY.md)
+- [Release Policy](RELEASE_POLICY.md)
+
+
+## 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:
+
+```sh
+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
 

package/action.yml

@@ -24,19 +24,19 @@ inputs:
     description: 'Repository URL for Git onboarding. Auto-detected from CI context when omitted.'
     required: false
   postman-access-token:
-    description: 'Postman access token for Bifrost API calls'
+    description: 'Service-account Postman access token for integration API calls. Prefer minting it with postman-resolve-service-token-action.'
     required: true
   postman-team-id:
-    description: 'Explicit Postman team ID for org-mode Bifrost request headers. When omitted, x-entity-team-id is not sent.'
+    description: 'Explicit Postman team ID for org-mode integration request headers. When omitted, x-entity-team-id is not sent.'
     required: false
   github-token:
     description: 'Optional GitHub token passed as git_api_key when repository auth is required by onboarding/git'
     required: false
   postman-api-key:
-    description: '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.'
+    description: '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.'
     required: false
   credential-preflight:
-    description: '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; off skips the identity probes entirely (the reactive error guidance still applies). A rejected or auto-created postman-api-key is never failed on.'
+    description: '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.'
     required: false
     default: 'warn'
   poll-timeout-seconds:
@@ -47,8 +47,12 @@ inputs:
     description: 'Seconds between discovery polling attempts'
     required: false
     default: '10'
+  postman-region:
+    description: 'Postman data residency region for public API calls. One of: us or eu.'
+    required: false
+    default: 'us'
   postman-stack:
-    description: 'Postman stack profile.'
+    description: 'Postman stack profile. Defaults to the public production stack. Marketplace workflows should leave this as prod.'
     required: false
     default: 'prod'
 outputs: