@catladder/pipeline 4.6.4 → 4.7.0

package/examples/cloud-run-verify.test.ts

@@ -0,0 +1,12 @@
+import { it, expect } from "vitest";
+import { createYamlLocalPipeline } from "./__utils__/helpers";
+import config from "./cloud-run-verify";
+
+/**
+ * This test is auto-generated.
+ * Modifications will be overwritten on every `yarn test` run!
+ */
+
+it("matches snapshot for cloud-run-verify local pipeline YAML", async () => {
+  expect(await createYamlLocalPipeline(config)).toMatchSnapshot();
+});

package/examples/cloud-run-verify.ts

@@ -0,0 +1,50 @@
+import type { Config } from "../src";
+
+const config = {
+  appName: "test-app",
+  customerName: "pan",
+  components: {
+    db: {
+      dir: "db",
+      build: {
+        type: "node",
+      },
+      deploy: {
+        type: "google-cloudrun",
+        projectId: "asdf",
+        region: "asia-east1",
+      },
+    },
+    api: {
+      dir: "api",
+      build: {
+        type: "node",
+      },
+      deploy: {
+        type: "google-cloudrun",
+        projectId: "asdf",
+        region: "asia-east1",
+        service: {
+          allowUnauthenticated: false,
+        },
+      },
+      verify: {
+        command: "yarn e2e",
+        waitFor: ["db"],
+      },
+      env: {
+        prod: {
+          verify: false,
+        },
+      },
+    },
+  },
+} satisfies Config;
+
+export default config;
+
+export const information = {
+  title: "Cloud Run: Post-deploy verify",
+  description:
+    "Runs an e2e suite in the verify stage after each deploy. The verify job waits for the db component's deploy, authenticates via application default credentials because the service is non-public, and is disabled for prod.",
+};

package/package.json

@@ -53,7 +53,7 @@
     }
   ],
   "license": "MIT",
-  "version": "4.6.4",
+  "version": "4.7.0",
   "scripts": {
     "build:tsc": "yarn tsc",
     "build": "yarn build:compile && yarn build:inline-variables",

package/src/deploy/cloudRun/index.ts

@@ -6,7 +6,10 @@ import {
 import type { BuildConfig } from "../../build";
 import { getSecretVarName } from "../../context";
 import type { EnvironmentContext } from "../../types/environmentContext";
-import { sanitizeForBashVariable } from "../../utils/gitlab";
+import {
+  collapseableSection,
+  sanitizeForBashVariable,
+} from "../../utils/gitlab";
 import { getFullDbName } from "../cloudSql/utils";
 import { createGoogleCloudRunDeployJobs } from "./createJobs";
 import { getCloudRunJobExecuteUrl } from "./utils/cloudRunExecutionUrl";
@@ -137,4 +140,23 @@ export const GCLOUD_RUN_DEPLOY_TYPE: DeployTypeDefinition<DeployConfigCloudRun>
           : undefined,
       };
     },
+    verifyJobSetupScript: (context) => {
+      const deployConfig = context.deploy?.config as
+        | DeployConfigCloudRun
+        | undefined;
+      const service = deployConfig?.service;
+      const serviceConfig = typeof service === "object" ? service : undefined;
+      if (serviceConfig?.allowUnauthenticated !== false) {
+        return [];
+      }
+      // the service requires IAM auth: provide application default credentials
+      // so the verify command can fetch identity tokens for the deployed service
+      return collapseableSection(
+        "verifygcloudauth",
+        "Setup google application credentials",
+      )([
+        `echo "$${GCLOUD_DEPLOY_CREDENTIALS_KEY}" > "$CI_PROJECT_DIR/.gcloud-sa.json"`,
+        `export GOOGLE_APPLICATION_CREDENTIALS="$CI_PROJECT_DIR/.gcloud-sa.json"`,
+      ]);
+    },
   };

package/src/deploy/index.ts

@@ -27,6 +27,11 @@ export type DeployTypeDefinition<D extends DeployConfig> = {
   getAdditionalEnvVars: (
     envContext: EnvironmentContext<BuildConfig, D>,
   ) => Record<string, string | BashExpression | undefined | null>;
+  /**
+   * script lines the deploy type contributes to the start of the verify job,
+   * e.g. to authenticate against a non-public service
+   */
+  verifyJobSetupScript?: (context: ComponentContext) => string[];
 };
 export type DeployTypes = {
   [T in DeployConfigType]: DeployTypeDefinition<DeployConfigGeneric<T>>;

package/src/index.ts

@@ -6,6 +6,7 @@ export * from "./config";
 export * from "./context";
 export * from "./build";
 export * from "./deploy";
+export * from "./verify";
 export * from "./utils/writeFiles";
 export * from "./utils/measureTime";
 export * from "./variables/VariableValue";

package/src/pipeline/createJobsForComponent.ts

@@ -5,6 +5,7 @@ import type {
   ComponentContextWithBuild,
 } from "../types/context";
 import type { CatladderJob } from "../types/jobs";
+import { createVerifyJobs } from "../verify/createVerifyJobs";
 
 const injectDefaultVarsInCustomJobs = (
   context: ComponentContext,
@@ -27,7 +28,7 @@ const getCustomJobs = (context: ComponentContext) => {
 export const createJobsForComponentContext = async (
   context: ComponentContext,
 ): Promise<CatladderJob[]> => {
-  const [buildJobs, deployJobs] = await Promise.all([
+  const [buildJobs, deployJobs, verifyJobs] = await Promise.all([
     context.build.type !== "disabled"
       ? BUILD_TYPES[context.build.buildType].jobs(
           context as ComponentContextWithBuild,
@@ -36,9 +37,10 @@ export const createJobsForComponentContext = async (
     context.componentConfig.deploy !== false
       ? DEPLOY_TYPES[context.componentConfig.deploy.type].jobs(context)
       : [],
+    createVerifyJobs(context),
   ]);
 
   const customJobs = getCustomJobs(context);
 
-  return [...buildJobs, ...deployJobs, ...customJobs];
+  return [...buildJobs, ...deployJobs, ...verifyJobs, ...customJobs];
 };

package/src/types/config.ts

@@ -8,6 +8,7 @@ import type { PipelineType, WorkspaceBuildConfig } from "..";
 import type { AgentConfig } from "./agent";
 import type { Hooks } from "./hooks";
 import type { ReleaseConfig } from "./release";
+import type { VerifyConfig } from "../verify/types";
 
 export const ALL_PIPELINE_TRIGGERS = [
   "mainBranch",
@@ -91,6 +92,14 @@ export type DefaultEnvConfig = {
    * environment variables
    */
   vars?: EnvVars;
+
+  /**
+   * post-deploy verification: runs a job in the `verify` stage after the deploy,
+   * e.g. an e2e test suite against the freshly deployed environment.
+   *
+   * Runs in all deployed envs by default, disable per env with `verify: false`
+   */
+  verify?: VerifyConfig | false;
 };
 
 export type DevLocalEnvConfig = {

package/src/verify/createVerifyJobs.ts

@@ -0,0 +1,81 @@
+import { createArtifactsConfig } from "../build/base/createArtifactsConfig";
+import { createJobCacheFromCacheConfigs } from "../build/cache/createJobCache";
+import { getNodeCache } from "../build/node/cache";
+import { NODE_RUNNER_BUILD_VARIABLES } from "../build/node/constants";
+import { ensureNodeVersion, getYarnInstall } from "../build/node/yarn";
+import { DEPLOY_TYPES } from "../deploy";
+import { DEPLOY_JOB_NAME } from "../deploy/base/deploy";
+import { getRunnerImage } from "../runner";
+import type { ComponentContext } from "../types/context";
+import type { CatladderJob } from "../types/jobs";
+import { ensureArray } from "../utils";
+
+export const VERIFY_JOB_NAME = "🔍 verify";
+
+export const createVerifyJobs = async (
+  context: ComponentContext,
+): Promise<CatladderJob[]> => {
+  const verifyConfig = context.componentConfig.verify;
+  if (!verifyConfig) {
+    return [];
+  }
+
+  const deployConfig = context.deploy?.config;
+  if (!deployConfig) {
+    // nothing is deployed, so there is nothing to verify
+    return [];
+  }
+
+  const isNodeBuild =
+    context.build.type !== "disabled" && context.build.buildType === "node";
+
+  const [yarnInstall, nodeCache] = isNodeBuild
+    ? await Promise.all([
+        getYarnInstall(context),
+        getNodeCache(context, "pull"),
+      ])
+    : [null, null];
+
+  const setupScript =
+    DEPLOY_TYPES[deployConfig.type].verifyJobSetupScript?.(context) ?? [];
+
+  return [
+    {
+      name: VERIFY_JOB_NAME,
+      stage: "verify",
+      envMode: "stagePerEnv",
+      // wait for this component's own deploy
+      needsStages: [{ stage: "deploy", artifacts: false }],
+      // ...and for the deploys of the components listed in waitFor
+      needs: (verifyConfig.waitFor ?? []).map((componentName) => ({
+        job: DEPLOY_JOB_NAME,
+        componentName,
+        artifacts: false,
+      })),
+      image: verifyConfig.jobImage ?? getRunnerImage("jobs-testing-chrome"),
+      cache: nodeCache
+        ? createJobCacheFromCacheConfigs(context, nodeCache)
+        : undefined,
+      variables: {
+        ...context.environment.envVars,
+      },
+      runnerVariables: {
+        ...NODE_RUNNER_BUILD_VARIABLES,
+        ...(verifyConfig.runnerVariables ?? {}),
+      },
+      script: [
+        ...setupScript,
+        ...(yarnInstall ? ensureNodeVersion(context) : []),
+        `cd ${context.build.dir}`,
+        ...(yarnInstall ?? []),
+        ...ensureArray(verifyConfig.command),
+      ],
+      allow_failure: verifyConfig.allowFailure,
+      ...createArtifactsConfig(
+        context.build.dir,
+        verifyConfig.artifactsReports,
+        verifyConfig.artifacts,
+      ),
+    },
+  ];
+};

package/src/verify/index.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./createVerifyJobs";

package/src/verify/types.ts

@@ -0,0 +1,18 @@
+import type { TestJobCustom } from "../build/types";
+
+/**
+ * post-deploy verification job configuration
+ */
+export type VerifyConfig = TestJobCustom & {
+  /**
+   * command(s) to run against the deployed environment (e.g. `yarn e2e`).
+   * Runs in the component's directory.
+   */
+  command: string | string[];
+
+  /**
+   * names of other components whose deploy must finish before this verify job runs
+   * (in addition to this component's own deploy, which is always awaited)
+   */
+  waitFor?: string[];
+};