@postman-cse/onboarding-insights 1.0.3 → 2.0.0

package/README.md

@@ -16,6 +16,8 @@ Part of the [Postman API Onboarding suite](https://github.com/postman-cs/postman
 
 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 |
@@ -40,12 +42,12 @@ jobs:
       # ... deploy your service to Kubernetes ...
 
       - id: postman_token
-        uses: postman-cs/postman-resolve-service-token-action@v1
+        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@v1
+      - uses: postman-cs/postman-insights-onboarding-action@v2
         with:
           project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
@@ -70,12 +72,12 @@ jobs:
       # ... deploy your service to Kubernetes ...
 
       - id: postman_token
-        uses: postman-cs/postman-resolve-service-token-action@v1
+        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@v1
+      - uses: postman-cs/postman-insights-onboarding-action@v2
         with:
           project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
@@ -99,12 +101,12 @@ jobs:
       - uses: actions/checkout@v5
 
       - id: postman_token
-        uses: postman-cs/postman-resolve-service-token-action@v1
+        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@v1
+      - uses: postman-cs/postman-bootstrap-action@v2
         id: bootstrap
         with:
           project-name: core-payments
@@ -115,7 +117,7 @@ jobs:
 
       # ... deploy service to Kubernetes ...
 
-      - uses: postman-cs/postman-repo-sync-action@v1
+      - uses: postman-cs/postman-repo-sync-action@v2
         id: sync
         with:
           project-name: core-payments
@@ -129,7 +131,7 @@ jobs:
           postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
           postman-access-token: ${{ steps.postman_token.outputs.token }}
 
-      - uses: postman-cs/postman-insights-onboarding-action@v1
+      - uses: postman-cs/postman-insights-onboarding-action@v2
         with:
           project-name: core-payments
           workspace-id: ${{ steps.bootstrap.outputs.workspace-id }}
@@ -147,7 +149,7 @@ jobs:
 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
+      - uses: postman-cs/postman-insights-onboarding-action@v2
         with:
           project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
@@ -165,7 +167,7 @@ The Insights agent takes time to discover services after pods start. The action
 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
+      - uses: postman-cs/postman-insights-onboarding-action@v2
         with:
           project-name: core-payments
           workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
@@ -201,13 +203,13 @@ See [CLI Usage](docs/cli.md) for provider auto-detection, output formats, and Gi
 <!-- inputs-table:start -->
 | Name | Description | Required | Default |
 | --- | --- | --- | --- |
-| `project-name` | Service name or spec ID to match against discovered service names | Yes |  |
+| `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. Matches {cluster}/{project-name} in discovered services | 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` | Service-account Postman access token for integration API calls. Prefer minting it with postman-resolve-service-token-action. | Yes |  |
+| `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 |  |

package/action.yml

@@ -6,7 +6,7 @@ branding:
   color: orange
 inputs:
   project-name:
-    description: 'Service name or spec ID to match against discovered service names'
+    description: 'Service name or Jira/Xray project key to match against the final discovered-service segment'
     required: true
   workspace-id:
     description: 'Postman workspace ID to link the discovered service to'
@@ -18,13 +18,13 @@ inputs:
     description: 'Postman system environment UUID for service-level Insights acknowledgment'
     required: false
   cluster-name:
-    description: 'Insights cluster name. Matches {cluster}/{project-name} in discovered services'
+    description: 'Insights cluster name. When set, matches {cluster-name}/{project-name} exactly in discovered services'
     required: false
   repo-url:
     description: 'Repository URL for Git onboarding. Auto-detected from CI context when omitted.'
     required: false
   postman-access-token:
-    description: 'Service-account Postman access token for integration API calls. Prefer minting it with postman-resolve-service-token-action.'
+    description: '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.'
     required: true
   postman-team-id:
     description: 'Explicit Postman team ID for org-mode integration request headers. When omitted, x-entity-team-id is not sent.'