Create @qawolf/ci-sdk API reference#143
Conversation
- Created qawolf/rest-overview.mdx - Created qawolf/deploy-success.mdx - Created qawolf/environment_terminated.mdx - Created qawolf/v0-ci-greenlight.mdx - Created qawolf/run-inputs-executables-signed-urls.mdx - Created qawolf/other-ci-node.mdx - Created qawolf/other-ci-webhook.mdx - Updated docs.json Mintlify-Source: dashboard-editor
- Updated qawolf/GitLab-2a15b2a994fb805d9d14ff27726065ae.mdx - Updated qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx - Updated qawolf/other-ci-webhook.mdx - Updated qawolf/other-ci-node.mdx - Updated qawolf/circle-ci.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/other-ci-node.mdx - Updated qawolf/other-ci-webhook.mdx - Updated qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx Mintlify-Source: dashboard-editor
- Created qawolf/libraries/ci-sdk/api-reference.mdx - Created qawolf/libraries/ci-sdk/troubleshooting.mdx - Updated docs.json Mintlify-Source: dashboard-editor
- Updated docs.json Mintlify-Source: dashboard-editor
- Updated qawolf/other-ci-node.mdx - Updated qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/libraries/ci-sdk/api-reference.mdx Mintlify-Source: dashboard-editor
John Gluck (JohnGluck)
requested review from
Mateus Zitelli (MateusZitelli) and
Eric Dobbertin (aldeed)
…s' into mktg-5566-document-qawolfci-sdk
- Updated qawolf/circle-ci.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/deploy-success.mdx - Updated qawolf/environment_terminated.mdx - Updated qawolf/v0-ci-greenlight.mdx - Updated qawolf/run-inputs-executables-signed-urls.mdx - Updated docs.json Mintlify-Source: dashboard-editor
- Updated qawolf/deploy-success.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/environment_terminated.mdx - Updated qawolf/deploy-success.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/v0-ci-greenlight.mdx - Updated qawolf/rest-overview.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/libraries/ci-sdk/api-reference.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx - Created qawolf/other-web-hook-for-mobile.mdx - Updated docs.json Mintlify-Source: dashboard-editor
- Updated qawolf/Fastlane-2db5b2a994fb802186a3d88573899c78.mdx - Updated qawolf/Integrate-a-mobile-build-with-GitHub-Actions-2db5b2a994fb8027a901d4238b02fb8f.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/Mobile-build-with-the-QA-Wolf-SDK-2db5b2a994fb80cdbd1ec31513f2cc15.mdx - Updated qawolf/other-web-hook-for-mobile.mdx - Updated qawolf/Integrate-a-mobile-build-with-GitHub-Actions-2db5b2a994fb8027a901d4238b02fb8f.mdx - Updated qawolf/other-ci-webhook.mdx - Updated qawolf/other-ci-node.mdx - Updated qawolf/circle-ci.mdx - Updated qawolf/GitLab-2a15b2a994fb805d9d14ff27726065ae.mdx - Updated qawolf/GitHub-GitHub-Actions-2a15b2a994fb800699f6dc99584915d0.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/libraries/ci-sdk/api-reference.mdx - Updated qawolf/other-ci-webhook.mdx - Updated qawolf/Uploading-manually.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/Uploading-manually.mdx Mintlify-Source: dashboard-editor
- Updated qawolf/Uploading-manually.mdx Mintlify-Source: dashboard-editor
Eric Dobbertin (aldeed)
left a comment
Eric Dobbertin (aldeed)
left a comment
There was a problem hiding this comment.
Various wording suggestions but this looks great, thanks!
| npm install @qawolf/ci-sdk | ||
| ``` | ||
|
|
||
| Requires Node.js 18 or later. For older versions, pass a `fetch` polyfill to `makeQaWolfSdk`: |
There was a problem hiding this comment.
I would remove the polyfill stuff and just say it requires 18. GitHub is soon dropping support for Node 20, let alone 18, so there is a good chance we'll just make Node 22 a hard requirement soon.
There is a mention of it in troubleshooting.mdx that would also need to be removed.
|
|
||
| ## makeQaWolfSdk | ||
|
|
||
| The entry point for all SDK functions. Pass your `QAWOLF_API_KEY` to initialize. |
There was a problem hiding this comment.
(Can be a later improvement)
I see a "Find the QAWOLF_API_KEY" section on each of the Deployment testing pages. Maybe we could make that its own "API Authentication" page, and link to it from every page that mentions QAWOLF_API_KEY? That's the pattern I see in most API docs I use.
There was a problem hiding this comment.
This needs to be argued with Kirk. I'll keep it for now, the principle being that having it on every page reduces cognitive load.
That said, Mintlify has a more robust way of sharing documentation blocks than notion so I'll open a ticket to refactor this so that if this changes for any reason, we'd only have to change it in one place.
There was a problem hiding this comment.
Sounds good. Either way.
|
|
||
| ## attemptNotifyDeploy | ||
|
|
||
| Notifies QA Wolf of a successful deployment to trigger a test run. See [webhooks/deploy\_success](/qawolf/deploy-success) for the underlying endpoint. |
There was a problem hiding this comment.
Instead of "to trigger a test run", it should say ", which may or may not start a test run".
|
|
||
| | Field | Type | Description | | ||
| | --- | --- | --- | | ||
| | `branch` | string | Git branch name. | |
There was a problem hiding this comment.
Generally we stick with the more generic "VCS" instead of "Git" because not all customers use Git (unless it's specific docs for GitHub or something).
| | `deploymentType` | string | Required if the target trigger matches on deployment type. | | ||
| | `deploymentUrl` | string | Overrides the environment URL. Available in tests as `process.env.URL`. | | ||
| | `hostingService` | string | `"GitHub"` or `"GitLab"`. Defaults to `"GitHub"`. | | ||
| | `commitUrl` | string | Pass with `sha` if no hosting service repo is configured. | |
There was a problem hiding this comment.
Add "Makes the commit ID a clickable link in the QA Wolf UI.", which the deploy_success field description has.
| | `httpStatus` | HTTP status code if the notification failed or was aborted due to a network error. | | ||
|
|
||
| <Note> | ||
| A run is only created if there is a matching trigger in your QA Wolf configuration. `outcome: "success"` means the notification was accepted, not that a run was created. |
There was a problem hiding this comment.
Maybe add "Check runId to know whether a run was created."
| | --- | --- | --- | | ||
| | `environmentId` | string | ID of the ephemeral environment. | | ||
| | `environmentAlias` | string | Alias of the ephemeral environment. | | ||
| | `deploymentUrl` | string | Preview URL used when the environment was created. | |
There was a problem hiding this comment.
Add:
This should be the same deploymentUrl you passed to attemptNotifyDeploy along with ephemeralEnvironment: true when originally notifying us.
| `POST https://app.qawolf.com/api/webhooks/deploy_success` | ||
|
|
||
| <Warning> | ||
| If your build server supports `node`, use [`@qawolf/ci-sdk`](/qawolf/libraries/ci-sdk/api-reference) instead of calling this endpoint directly. |
There was a problem hiding this comment.
To explain why, you could add "This gives you type safety and clearer errors and output."
| @@ -0,0 +1,66 @@ | |||
| --- | |||
| title: "webhooks/environment_terminated" | |||
| description: 'Stops all runs targeting the environment and triggers flow promotion to the static base environment. The environment will show as "closed" in QA Wolf.' | |||
There was a problem hiding this comment.
"requests" might be better than "triggers". Often the environment can't be auto-promoted so it just goes into a queue. This is the promotionTaskId in the response.
|
|
||
| ## Request body | ||
|
|
||
| All fields are optional. |
There was a problem hiding this comment.
They are not really optional. It would be more accurate to use the same text from ci-sdk:
Pass one of the following to identify the environment:
2 participants
This PR creates 3 new docs in our standard API Reference format for
@qawolf/ci-sdk0 threads from 0 users in Mintlify