@postman-cse/onboarding-insights 1.0.0 → 1.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +106 -157
- package/action.yml +2 -2
- package/package.json +2 -1
package/README.md
CHANGED
|
@@ -1,33 +1,43 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Postman Insights Onboarding
|
|
2
2
|
|
|
3
3
|
[](https://github.com/postman-cs/postman-insights-onboarding-action/actions/workflows/ci.yml)
|
|
4
4
|
[](https://github.com/postman-cs/postman-insights-onboarding-action/releases)
|
|
5
5
|
[](https://www.npmjs.com/package/@postman-cse/onboarding-insights)
|
|
6
6
|
[](LICENSE)
|
|
7
7
|
|
|
8
|
-
|
|
8
|
+
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.
|
|
9
9
|
|
|
10
|
-
##
|
|
10
|
+
## Usage
|
|
11
11
|
|
|
12
|
-
|
|
12
|
+
```yaml
|
|
13
|
+
jobs:
|
|
14
|
+
deploy:
|
|
15
|
+
runs-on: ubuntu-latest
|
|
16
|
+
steps:
|
|
17
|
+
- uses: actions/checkout@v5
|
|
13
18
|
|
|
14
|
-
|
|
15
|
-
- Prepares an API Catalog collection for the discovered service in your workspace.
|
|
16
|
-
- Links the service to a GitHub repository through the API Catalog git onboarding flow.
|
|
17
|
-
- Acknowledges the service and workspace with the Insights backend (Akita).
|
|
18
|
-
- Creates an application binding with the observability API (required for service graph edges).
|
|
19
|
-
- Retrieves the team verification token for DaemonSet telemetry.
|
|
19
|
+
# ... deploy your service to Kubernetes ...
|
|
20
20
|
|
|
21
|
-
|
|
21
|
+
- uses: postman-cs/postman-insights-onboarding-action@v1
|
|
22
|
+
with:
|
|
23
|
+
project-name: af-cards-activation
|
|
24
|
+
workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
|
|
25
|
+
environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
|
|
26
|
+
postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
|
|
27
|
+
```
|
|
22
28
|
|
|
23
|
-
|
|
29
|
+
### Prerequisites
|
|
24
30
|
|
|
25
31
|
- The Postman Insights DaemonSet agent must be running on your cluster in discovery mode.
|
|
26
32
|
- The target service must be deployed and running (the agent discovers it from live traffic).
|
|
27
33
|
- A Postman workspace and environment must already exist for the service.
|
|
28
|
-
- A `postman-access-token` (session token) is required for Bifrost API access.
|
|
34
|
+
- A `postman-access-token` (session token) is required for Bifrost API access. See [Credentials and Identity](docs/credentials.md).
|
|
29
35
|
|
|
30
|
-
|
|
36
|
+
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.
|
|
37
|
+
|
|
38
|
+
## Examples
|
|
39
|
+
|
|
40
|
+
### Standalone after a Kubernetes deploy
|
|
31
41
|
|
|
32
42
|
```yaml
|
|
33
43
|
jobs:
|
|
@@ -50,7 +60,7 @@ jobs:
|
|
|
50
60
|
poll-timeout-seconds: 180
|
|
51
61
|
```
|
|
52
62
|
|
|
53
|
-
###
|
|
63
|
+
### Full onboarding pipeline
|
|
54
64
|
|
|
55
65
|
```yaml
|
|
56
66
|
jobs:
|
|
@@ -93,179 +103,118 @@ jobs:
|
|
|
93
103
|
github-token: ${{ secrets.GITHUB_TOKEN }}
|
|
94
104
|
```
|
|
95
105
|
|
|
96
|
-
|
|
97
|
-
|
|
98
|
-
The CLI is available for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems. GitHub Actions users should continue using the `action.yml` interface.
|
|
99
|
-
|
|
100
|
-
Install globally:
|
|
106
|
+
### Tuning discovery polling
|
|
101
107
|
|
|
102
|
-
|
|
103
|
-
npm install -g postman-insights-onboarding-action
|
|
104
|
-
```
|
|
108
|
+
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:
|
|
105
109
|
|
|
106
|
-
|
|
107
|
-
|
|
108
|
-
|
|
109
|
-
|
|
110
|
-
|
|
111
|
-
|
|
112
|
-
|
|
113
|
-
|
|
114
|
-
|
|
115
|
-
--cluster-name my-cluster \
|
|
116
|
-
--repo-url https://gitlab.com/acme/af-cards-activation \
|
|
117
|
-
--poll-timeout-seconds 180 \
|
|
118
|
-
--result-json /tmp/insights-result.json \
|
|
119
|
-
--dotenv-path /tmp/insights.env
|
|
110
|
+
```yaml
|
|
111
|
+
- uses: postman-cs/postman-insights-onboarding-action@v1
|
|
112
|
+
with:
|
|
113
|
+
project-name: af-cards-activation
|
|
114
|
+
workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
|
|
115
|
+
environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
|
|
116
|
+
postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
|
|
117
|
+
poll-timeout-seconds: 300
|
|
118
|
+
poll-interval-seconds: 15
|
|
120
119
|
```
|
|
121
120
|
|
|
122
|
-
|
|
121
|
+
`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.
|
|
123
122
|
|
|
124
|
-
|
|
123
|
+
### Credential preflight modes
|
|
125
124
|
|
|
126
|
-
|
|
125
|
+
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):
|
|
127
126
|
|
|
128
127
|
```yaml
|
|
129
|
-
onboarding
|
|
130
|
-
|
|
131
|
-
|
|
132
|
-
|
|
133
|
-
|
|
128
|
+
- uses: postman-cs/postman-insights-onboarding-action@v1
|
|
129
|
+
with:
|
|
130
|
+
project-name: af-cards-activation
|
|
131
|
+
workspace-id: ${{ vars.POSTMAN_WORKSPACE_ID }}
|
|
132
|
+
environment-id: ${{ vars.POSTMAN_ENVIRONMENT_ID }}
|
|
133
|
+
postman-access-token: ${{ secrets.POSTMAN_ACCESS_TOKEN }}
|
|
134
|
+
postman-api-key: ${{ secrets.POSTMAN_API_KEY }}
|
|
135
|
+
credential-preflight: enforce
|
|
134
136
|
```
|
|
135
137
|
|
|
136
|
-
|
|
138
|
+
See [Credentials and Identity](docs/credentials.md) for the full policy, API key auto-creation behavior, and how to obtain the access token.
|
|
137
139
|
|
|
138
|
-
|
|
139
|
-
image: node:24
|
|
140
|
-
|
|
141
|
-
pipelines:
|
|
142
|
-
default:
|
|
143
|
-
- step:
|
|
144
|
-
script:
|
|
145
|
-
- npm install -g postman-insights-onboarding-action
|
|
146
|
-
- postman-insights-onboard --project-name af-cards-activation --workspace-id "$WORKSPACE_ID" --environment-id "$ENVIRONMENT_ID" --postman-access-token "$POSTMAN_ACCESS_TOKEN" --postman-api-key "$POSTMAN_API_KEY" --cluster-name "$CLUSTER_NAME" --repo-url "$BITBUCKET_GIT_HTTP_ORIGIN" --poll-timeout-seconds 180 --result-json insights-result.json --dotenv-path insights.env
|
|
147
|
-
```
|
|
140
|
+
### Non-GitHub CI via the CLI
|
|
148
141
|
|
|
149
|
-
|
|
142
|
+
The same logic ships as a CLI (`postman-insights-onboard`) for GitLab CI, Bitbucket Pipelines, Azure DevOps, and other CI systems:
|
|
150
143
|
|
|
151
|
-
```
|
|
152
|
-
|
|
153
|
-
|
|
154
|
-
|
|
155
|
-
|
|
156
|
-
-
|
|
157
|
-
|
|
158
|
-
|
|
159
|
-
- script: |
|
|
160
|
-
npm install -g postman-insights-onboarding-action
|
|
161
|
-
postman-insights-onboard --project-name af-cards-activation --workspace-id "$(WORKSPACE_ID)" --environment-id "$(ENVIRONMENT_ID)" --postman-access-token "$(POSTMAN_ACCESS_TOKEN)" --postman-api-key "$(POSTMAN_API_KEY)" --cluster-name "$(CLUSTER_NAME)" --repo-url "$(BUILD_REPOSITORY_URI)" --poll-timeout-seconds 180 --result-json insights-result.json --dotenv-path insights.env
|
|
162
|
-
displayName: Run Postman Insights onboarding
|
|
144
|
+
```bash
|
|
145
|
+
npm install -g @postman-cse/onboarding-insights
|
|
146
|
+
postman-insights-onboard \
|
|
147
|
+
--project-name af-cards-activation \
|
|
148
|
+
--workspace-id ws_123 \
|
|
149
|
+
--environment-id env_123 \
|
|
150
|
+
--postman-access-token "$POSTMAN_ACCESS_TOKEN" \
|
|
151
|
+
--cluster-name my-cluster
|
|
163
152
|
```
|
|
164
153
|
|
|
154
|
+
See [CLI Usage](docs/cli.md) for provider auto-detection, output formats, and GitLab/Bitbucket/Azure pipeline examples.
|
|
155
|
+
|
|
165
156
|
## Inputs
|
|
166
157
|
|
|
167
|
-
|
|
158
|
+
<!-- inputs-table:start -->
|
|
159
|
+
| Name | Description | Required | Default |
|
|
168
160
|
| --- | --- | --- | --- |
|
|
169
|
-
| `project-name` |
|
|
170
|
-
| `workspace-id` |
|
|
171
|
-
| `environment-id` |
|
|
172
|
-
| `system-environment-id` |
|
|
173
|
-
| `cluster-name` |
|
|
174
|
-
| `repo-url` |
|
|
175
|
-
| `postman-access-token` |
|
|
176
|
-
| `postman-team-id` |
|
|
177
|
-
| `github-token` |
|
|
178
|
-
| `postman-api-key` |
|
|
179
|
-
| `
|
|
180
|
-
| `poll-
|
|
181
|
-
|
|
182
|
-
|
|
183
|
-
|
|
184
|
-
|
|
185
|
-
|
|
186
|
-
### Obtaining `postman-access-token` (Customer Preview)
|
|
187
|
-
|
|
188
|
-
> **Customer Preview limitation:** The `postman-access-token` input requires a manually-extracted session token. There is currently no public API to exchange a Postman API key (PMAK) for an access token programmatically. This manual step will be eliminated before GA.
|
|
189
|
-
|
|
190
|
-
The `postman-access-token` is a Postman session token (`x-access-token`) required for the Bifrost API Catalog onboarding endpoints. Without it, this action cannot function.
|
|
191
|
-
|
|
192
|
-
**To obtain and configure the token:**
|
|
193
|
-
|
|
194
|
-
1. **Log in via the Postman CLI** (requires a browser):
|
|
195
|
-
```bash
|
|
196
|
-
postman login
|
|
197
|
-
```
|
|
198
|
-
|
|
199
|
-
2. **Extract the access token:**
|
|
200
|
-
```bash
|
|
201
|
-
cat ~/.postman/postmanrc | jq -r '.login._profiles[].accessToken'
|
|
202
|
-
```
|
|
203
|
-
|
|
204
|
-
3. **Set it as a GitHub secret:**
|
|
205
|
-
```bash
|
|
206
|
-
gh secret set POSTMAN_ACCESS_TOKEN --repo <owner>/<repo>
|
|
207
|
-
```
|
|
208
|
-
|
|
209
|
-
> **Important:** This token is session-scoped and will expire. When it does, the action will fail. You will need to repeat the login and secret update process.
|
|
161
|
+
| `project-name` | Service name or spec ID to match against discovered service names | Yes | |
|
|
162
|
+
| `workspace-id` | Postman workspace ID to link the discovered service to | Yes | |
|
|
163
|
+
| `environment-id` | Postman environment UID for the onboarding association | Yes | |
|
|
164
|
+
| `system-environment-id` | Postman system environment UUID for service-level Insights acknowledgment | No | |
|
|
165
|
+
| `cluster-name` | Insights cluster name. Matches {cluster}/{project-name} in discovered services | No | |
|
|
166
|
+
| `repo-url` | Repository URL for Git onboarding. Auto-detected from CI context when omitted. | No | |
|
|
167
|
+
| `postman-access-token` | Postman access token for Bifrost API calls | Yes | |
|
|
168
|
+
| `postman-team-id` | Explicit Postman team ID for org-mode Bifrost request headers. When omitted, x-entity-team-id is not sent. | No | |
|
|
169
|
+
| `github-token` | Optional GitHub token passed as git_api_key when repository auth is required by onboarding/git | No | |
|
|
170
|
+
| `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 | |
|
|
171
|
+
| `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` |
|
|
172
|
+
| `poll-timeout-seconds` | Maximum seconds to wait for the service to appear in the discovered list | No | `120` |
|
|
173
|
+
| `poll-interval-seconds` | Seconds between discovery polling attempts | No | `10` |
|
|
174
|
+
<!-- inputs-table:end -->
|
|
175
|
+
|
|
176
|
+
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).
|
|
210
177
|
|
|
211
178
|
## Outputs
|
|
212
179
|
|
|
213
|
-
|
|
214
|
-
|
|
|
215
|
-
|
|
|
216
|
-
| `discovered-service-
|
|
217
|
-
| `
|
|
218
|
-
| `
|
|
219
|
-
| `
|
|
220
|
-
| `
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
224
|
-
The Insights agent takes time to discover services after pods start. This action polls the API Catalog discovered-services list at the configured interval until the service appears or the timeout is reached.
|
|
225
|
-
|
|
226
|
-
- Default timeout: 120 seconds (configurable via `poll-timeout-seconds`, clamped to 10--600).
|
|
227
|
-
- Default interval: 10 seconds (configurable via `poll-interval-seconds`, clamped to 2--60).
|
|
228
|
-
- If the service is not found after the timeout, the action sets `status` to `not-found` and emits a warning (does not fail the workflow).
|
|
180
|
+
<!-- outputs-table:start -->
|
|
181
|
+
| Name | Description | Required | Default |
|
|
182
|
+
| --- | --- | --- | --- |
|
|
183
|
+
| `discovered-service-id` | Numeric ID from the API Catalog discovered-services list | | |
|
|
184
|
+
| `discovered-service-name` | Full cluster/service name of the discovered service | | |
|
|
185
|
+
| `collection-id` | Collection ID returned by the prepare-collection step | | |
|
|
186
|
+
| `application-id` | Insights application binding ID from the observability API | | |
|
|
187
|
+
| `verification-token` | Insights team verification token (tvt_*) for DaemonSet telemetry | | |
|
|
188
|
+
| `status` | Onboarding result: success, not-found, or error | | |
|
|
189
|
+
<!-- outputs-table:end -->
|
|
229
190
|
|
|
230
|
-
|
|
191
|
+
Failures set `status=error` before the action exits.
|
|
231
192
|
|
|
232
193
|
## How it works
|
|
233
194
|
|
|
234
|
-
The action
|
|
195
|
+
**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.
|
|
235
196
|
|
|
236
|
-
|
|
237
|
-
2. **Prepare collection** -- `POST /api/v1/onboarding/prepare-collection` (Bifrost api-catalog) to create the API Catalog collection entry.
|
|
238
|
-
3. **Onboard git** -- `POST /api/v1/onboarding/git` (Bifrost api-catalog) with `via_integrations: false` to link the service to the GitHub repository.
|
|
239
|
-
4. **Resolve provider service ID** -- `GET /v2/api-catalog/services?status=discovered&...` (Bifrost akita) to find the `svc_*` Akita service ID.
|
|
240
|
-
5. **Service-level acknowledge** -- `POST /v2/api-catalog/services/onboard` (Bifrost akita) to mark the service as managed.
|
|
241
|
-
6. **Application binding** -- `POST /v2/agent/api-catalog/workspaces/{id}/applications` (direct to `api.observability.postman.com`, NOT Bifrost) to bind the workspace to the Insights application. Required for service graph edge generation.
|
|
242
|
-
7. **Workspace acknowledge** -- `POST /v2/workspaces/{id}/onboarding/acknowledge` (Bifrost akita) to activate the Insights project.
|
|
243
|
-
8. **Team verification token** -- `GET /v2/workspaces/{id}/team-verification-token` (Bifrost akita) to retrieve the DaemonSet telemetry token.
|
|
197
|
+
**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.
|
|
244
198
|
|
|
245
|
-
|
|
199
|
+
**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).
|
|
246
200
|
|
|
247
|
-
|
|
201
|
+
**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.
|
|
248
202
|
|
|
249
|
-
|
|
203
|
+
**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.
|
|
250
204
|
|
|
251
|
-
|
|
252
|
-
- `SMOKE_ORG_ACCESS_TOKEN`
|
|
205
|
+
For local builds, contract smoke monitoring, and release channels, see [Development and Operations](docs/development.md).
|
|
253
206
|
|
|
254
|
-
|
|
255
|
-
|
|
256
|
-
## Local development
|
|
257
|
-
|
|
258
|
-
```bash
|
|
259
|
-
npm install
|
|
260
|
-
npm test
|
|
261
|
-
npm run typecheck
|
|
262
|
-
npm run build
|
|
263
|
-
```
|
|
207
|
+
## Resources
|
|
264
208
|
|
|
265
|
-
|
|
209
|
+
- [postman-resolve-service-token-action](https://github.com/postman-cs/postman-resolve-service-token-action): mints a service-account access token and team ID.
|
|
210
|
+
- [postman-api-onboarding-action](https://github.com/postman-cs/postman-api-onboarding-action): composite action that orchestrates the onboarding pipeline.
|
|
211
|
+
- [postman-bootstrap-action](https://github.com/postman-cs/postman-bootstrap-action): workspace provisioning, spec upload, and collection generation.
|
|
212
|
+
- [postman-smoke-flow-action](https://github.com/postman-cs/postman-smoke-flow-action): applies a curated flow.yaml to the canonical Smoke collection.
|
|
213
|
+
- [postman-repo-sync-action](https://github.com/postman-cs/postman-repo-sync-action): artifact sync, environments, mocks, monitors, and CI templates.
|
|
214
|
+
- [postman-aws-spec-discovery-action](https://github.com/postman-cs/postman-aws-spec-discovery-action): discovers API specs from AWS.
|
|
215
|
+
- npm package: [@postman-cse/onboarding-insights](https://www.npmjs.com/package/@postman-cse/onboarding-insights)
|
|
216
|
+
- [Postman Insights documentation](https://learning.postman.com/docs/insights/insights-overview/)
|
|
266
217
|
|
|
267
|
-
##
|
|
218
|
+
## License
|
|
268
219
|
|
|
269
|
-
|
|
270
|
-
- Consumers can pin immutable tags such as `v1.0.0` for reproducibility.
|
|
271
|
-
- Moving tag `v1` is used as the rolling customer preview channel.
|
|
220
|
+
[MIT](LICENSE)
|
package/action.yml
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
|
-
name: '
|
|
2
|
-
description: 'Link Postman Insights discovered services to API Catalog workspaces and git
|
|
1
|
+
name: 'Postman Insights Onboarding'
|
|
2
|
+
description: 'Link Postman Insights discovered services to API Catalog workspaces and git repositories after deployment.'
|
|
3
3
|
author: Postman
|
|
4
4
|
branding:
|
|
5
5
|
icon: link
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@postman-cse/onboarding-insights",
|
|
3
|
-
"version": "1.0.
|
|
3
|
+
"version": "1.0.1",
|
|
4
4
|
"description": "GitHub Action to onboard Postman Insights discovered services to API Catalog workspaces.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "dist/index.cjs",
|
|
@@ -17,6 +17,7 @@
|
|
|
17
17
|
"scripts": {
|
|
18
18
|
"build": "rm -rf dist && esbuild src/index.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/index.cjs && esbuild src/main.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/action.cjs && esbuild src/cli.ts --bundle --platform=node --target=node24 --format=cjs --outfile=dist/cli.cjs",
|
|
19
19
|
"check:dist": "npm run build && git diff --exit-code -- dist",
|
|
20
|
+
"docs:tables": "node scripts/render-action-tables.mjs --write",
|
|
20
21
|
"lint": "eslint .",
|
|
21
22
|
"lint:fix": "eslint . --fix",
|
|
22
23
|
"test": "vitest run",
|