@qawolf/ci-sdk 0.23.1 → 1.1.0

package/README.md

@@ -1,17 +1,9 @@
 # QAWolf CI SDK
 
-> :warning: This is an experimental package. Please report any
-> issues you encounter to your support channel. It should still
-> provide a better experience than using our internal GraphQL
-> API directly.
-
 This package provides a TypeScript (CSM and ESM compatible) SDK
 to interact with the QA Wolf Customer-facing API.
 
-It exposes two functions associated with the two central endpoints, showcased in
-the examples below. There is also an experimental VCS Branch Testing (aka PR Testing)
-feature, encapsulated in its own object, that is described at the bottom of this
-document.
+It exposes several functions associated with different endpoints, which are detailed in the table of contents below.
 
 Note that these functions do not throw. They yield a result object that
 contains the outcome of the operation. This outcome should be scrutinized
@@ -86,6 +78,19 @@ const deployConfig: GitLabDeployConfig = {
   },
 };
 
+// Example for Ephemeral deployments
+const deployConfig: EphemeralDeployConfig = {
+  branch: undefined,
+  commitUrl: undefined,
+  deduplicationKey: undefined,
+  // Required only if the target trigger requires matching a deployment type
+  deploymentType: "staging", // e.g., "production", "staging", "qa"
+  deploymentUrl: "https://preview.environment.com",
+  ephemeralEnvironment: true,
+  sha: undefined,
+  variables: undefined,
+};
+
 // General Example
 // Edit this to your needs.
 const deployConfig: DeployConfig = {
@@ -133,7 +138,9 @@ Once enabled, to use PR/MR testing functionality:
 
    - Pass `hostingService: "GitLab"`, `repository` information, and `mergeRequestNumber` while notifying a deployment as described in the [Notify Deployment](#notify-deployment) section
 
-3. For other version control systems see below section [VCS Branch Testing (Experimental)](#vcs-branch-testing)
+3. For `Ephemeral` deployments (no code hosting integration):
+
+   - Pass `ephemeralEnvironment: true` and `deploymentUrl` while notifying a deployment as described in the [Notify Deployment](#notify-deployment) section
 
 <a id="ci-greenlight"></a>
 
@@ -249,191 +256,6 @@ async function uploadRunArtifact(filePath: string): Promise<string> {
 }
 ```
 
-<a name="vcs-branch-testing"></a>
-
-## VCS Branch Testing (Experimental)
-
-> ⚠️ For GitHub and GitLab users, we recommend using the standard notify deployment approach described in [Notify Preview Deployment (Pull Request / Merge Request Testing)](#notify-preview). The standard approach provides better integration with your repository when you include the proper repository and PR/MR information.
-
-> ⚠️ This section is not covered by SemVer and will change.
-
-> ℹ️ This feature must be activated by QA Wolf. Please reach out to a QA Wolf
-> representative to enable it, and help you with the setup.
-
-### Highlights and Definitions
-
-VCS Branch Testing allows you to set up QA Wolf ephemeral environments associated with
-preview deployments (builds) of your product, which code is hosted in VCS branches (e.g.
-Git branches). It can be understood as "PR Testing", however the SDK does not need
-the concept of PR or MR to operate.
-
-> ℹ️ Read our [introduction to VCS Branch Testing](https://qawolf.notion.site/VCS-Branch-Testing-45be5d10d93249aeb8c1f995d26356ec?pvs=4) to get familiar with core concepts. We also provide [a more detailed SDK guide over here](https://qawolf.notion.site/qawolf-ci-sdk-VCS-Branch-Testing-df701e8742b84be39632d7284c926491?pvs=74).
-
-### Usage
-
-This SDK exposes an experimental VCS Branch Testing object:
-
-```ts
-import { makeQaWolfSdk } from "@qawolf/ci-sdk";
-
-const vcsBranchTestingSdk = makeQaWolfSdk({
-  apiKey: "qawolf_xxxxx",
-}).experimental_vcsBranchTesting;
-```
-
-The above object contains the following methods:
-
-- `notifyVCSBranchBuildDeployed`;
-- `notifyVCSBranchMergeCanceled`;
-- `notifyVCSBranchMergeCompleted`.
-
-#### Notify Build Deployed `notifyVCSBranchBuildDeployed`
-
-```ts
-import {
-  makeQaWolfSdk,
-  arbitraryStringToEnvironmentAlias,
-} from "@qawolf/ci-sdk";
-
-const { notifyVCSBranchBuildDeployed } = makeQaWolfSdk({
-  apiKey: "qawolf_xxxxx",
-}).experimental_vcsBranchTesting;
-
-// Mappings let QA Wolf know how to associate base VCS branches to environments.
-const baseEnvironmentsMapping = [
-  {
-    environmentAlias: "develop",
-    vcsBranch: "main",
-  },
-];
-
-(async () => {
-  const baseVcsBranch = "main";
-  const headVcsBranch = "feature/foo";
-  const headPreviewUrl = "https://feature-foo.example.com";
-  const headVcsCommitId = "abcdef";
-  // Optional. It will show up in the UI when provided. If an integration with
-  // a code hosting service is already set up, you don't need to provide this field.
-  const optionalHeadCommitUrl = "https://.../commits/abcdef";
-  // Optional. It is required for a code hosting service integration to function
-  // properly. When that is the case, comments will be posted in the PR/MR describing
-  // the outcome of tests in the head environment.
-  const optionalPullOrMergeRequestNumber = 123;
-  // The alias must be stable for the lifetime of the VCS Branch / Environment.
-  // It also should be unique across your organization, accounting for different
-  // repositories.
-  const headEnvironmentAlias = arbitraryStringToEnvironmentAlias(
-    `org/repo/${headVcsBranch}`,
-  );
-  // The name of the environment, as it will show-up in the QA Wolf UI.
-  const headEnvironmentName = `org/repo/${headVcsBranch}`;
-  // Environment variables are not optional. There must be at least one locator
-  // for the deployed application. Since this deployment is entirely handled by
-  // customers, we cannot provide more generic guidance.
-  const headEnvironmentVariables = {
-    URL: headPreviewUrl,
-  };
-  // Obviously, configuration object should be adapted to your needs, and
-  // most are dynamic and shall be derived from context. This is just an example.
-  const { outcome } = await notifyVCSBranchBuildDeployed({
-    baseEnvironmentsMapping,
-    baseVcsBranch: "main",
-    headEnvironmentAlias,
-    // If you are not sure how to build the environment name, just use the
-    // alias. This name will show up in the UI though.
-    headEnvironmentName,
-    headVcsBranch,
-    headVcsCommitId,
-    headCommitUrl: optionalHeadCommitUrl,
-    headEnvironmentVariables,
-    pullOrMergeRequestNumber: optionalPullOrMergeRequestNumber,
-  });
-  if (outcome !== "success") {
-    // Fail the job.
-    process.exit(1);
-  }
-  // Continue CI.
-})();
-```
-
-#### Notify Merge Canceled `notifyVCSBranchMergeCanceled`
-
-```ts
-import { makeQaWolfSdk } from "@qawolf/ci-sdk";
-
-const { notifyVCSBranchMergeCanceled } = makeQaWolfSdk({
-  apiKey: "qawolf_xxxxx",
-}).experimental_vcsBranchTesting;
-
-(async () => {
-  const headVcsBranch = "feature/foo";
-  // The alias must be stable for the lifetime of the VCS Branch / Environment.
-  // It also should be unique across your organization, accounting for different
-  // repositories.
-  const headEnvironmentAlias = arbitraryStringToEnvironmentAlias(
-    `org/repo/${headVcsBranch}`,
-  );
-  const result = await notifyVCSBranchMergeCanceled({
-    headEnvironmentAlias,
-  });
-  if (result.outcome !== "success") {
-    if (result.abortReason === "head-environment-not-found") {
-      console.warn(
-        `Head environment not found. Skipping! The QA Wolf environment was either never created or it was manually deleted.`,
-      );
-      return;
-    }
-    // Fail the job.
-    process.exit(1);
-  }
-  // Continue CI.
-})();
-```
-
-### Notify Merge Completed `notifyVCSBranchMergeCompleted`
-
-```ts
-import {
-  makeQaWolfSdk,
-  arbitraryStringToEnvironmentAlias,
-} from "@qawolf/ci-sdk";
-
-const { notifyVCSBranchMergeCompleted } = makeQaWolfSdk({
-  apiKey: "qawolf_xxxxx",
-}).experimental_vcsBranchTesting;
-
-// Mappings let QA Wolf know how to associate base VCS branches to environments.
-const baseEnvironmentsMapping = [
-  {
-    environmentAlias: "develop",
-    vcsBranch: "main",
-  },
-];
-
-(async () => {
-  const headVcsBranch = "feature/foo";
-  // The alias must be stable for the lifetime of the VCS Branch / Environment.
-  // It also should be unique across your organization, accounting for different
-  // repositories.
-  const headEnvironmentAlias = arbitraryStringToEnvironmentAlias(
-    `org/repo/${headVcsBranch}`,
-  );
-  const baseVcsBranch = "main";
-
-  const { outcome } = await notifyVCSBranchMergeCompleted({
-    baseEnvironmentsMapping,
-    headVcsBranch,
-    headEnvironmentAlias,
-    baseVcsBranch,
-  });
-  if (outcome !== "success") {
-    // Fail the job.
-    process.exit(1);
-  }
-  // Continue CI.
-})();
-```
-
 <a name="requirements"></a>
 
 ## Requirements
@@ -458,9 +280,7 @@ const sdk = makeQaWolfSdk(
 
 This package follows the [SemVer](https://semver.org/) versioning scheme. Additional notes:
 
-- Versions below 1.0.0 still follow this scheme.
-- We recommend depending on the `^` range operator for this package, as it will not introduce breaking changes and guarantee
-an up-to-date API usage version.
+- We recommend depending on the `^` range operator for this package, as it will not introduce breaking changes and guarantee an up-to-date API usage version.
 <!-- There is a limitation in NPM preventing us from using relative links and hosting other MD files when the repository hosting code is not
   public, hence we inline the changelog in the README. See https://github.com/npm/feedback/discussions/666 -->
 - We will provide a changelog for each release, which will be available in the Changelog section below.
@@ -474,6 +294,18 @@ an up-to-date API usage version.
 
 # Changelog
 
+## v1.1.0
+
+- New `ephemeralEnvironment` parameter for `attemptNotifyDeploy`
+
+## v1.0.1
+
+- Internal ESM-related refactoring
+
+## v1.0.0
+
+- Breaking Change: Remove `experimental_vcsBranchTesting` and `experimental_testPreview`. See how to migrate in [Notify Preview Deployment (Pull Request / Merge Request Testing)](#notify-preview) section.
+
 ## v0.23.1
 
 - Fix ESM build