ci: automate releases

Publishing this app is manual today, and the repo drifted from what Zapier
runs: #99 had to reconstruct 4.10.0 through 4.14.0 out of the published app
and back into git.

Bump the minor version and write the changelog entry in the same PR as the
code. CI fails the PR when code that reaches Zapier changes without that.
Merging uploads that version to Zapier and promotes it, so new Zaps get it.
Existing Zaps keep the version they were built on, because nothing migrates
them.

The release workflow asks Zapier which versions it holds rather than
inferring from the push, so a release that never arrived is retried on the
next push to master, or from the Actions tab. That is also why there is one
workflow here and not three.

Check the promote step. It passes --yes, without which the CLI waits on a
prompt nobody can answer on a runner, and that flag also accepts Zapier's
non-blocking pre-check warnings.

The repo moves to Node 22, because the Zapier CLI that CI installs pulls
dependencies that refuse to install below Node 20. Zapier still runs this app on Node 18,
and will until we move to core 17.

Towards INF-3414

Author: eliias

.github/workflows/nodejs.yml

@@ -8,12 +8,14 @@ jobs:
 
     strategy:
       matrix:
-        node-version: [18.19.1]
+        node-version: [22.23.2]
 
     steps:
-      - uses: actions/checkout@v1
+      - uses: actions/checkout@v7
+        with:
+          persist-credentials: false
       - name: Use Node.js ${{ matrix.node-version }}
-        uses: actions/setup-node@v1
+        uses: actions/setup-node@v7
         with:
           node-version: ${{ matrix.node-version }}
       - name: yarn, build, and test
@@ -25,3 +27,62 @@ jobs:
           NODE_ENV: test
           LINEAR_API_KEY: ${{ secrets.LINEAR_API_KEY }}
           LINEAR_TEAM_ID: ${{ secrets.LINEAR_TEAM_ID }}
+      - name: Install the Zapier CLI
+        run: |
+          npm install --no-save --prefix "$RUNNER_TEMP/cli" zapier-platform-cli@19.1.0
+          echo "$RUNNER_TEMP/cli/node_modules/.bin" >> "$GITHUB_PATH"
+      - name: Validate the Zapier schema
+        run: |
+          yarn zapier-build
+          zapier-platform validate --without-style
+
+  version:
+    name: Version bump
+    if: github.ref_name != 'master'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+
+      - name: Require a version bump for shipped changes
+        run: |
+          git fetch --no-tags origin master
+          base=$(git merge-base origin/master HEAD)
+
+          changed=$(git diff --name-only "$base..HEAD" -- src index.js tsconfig.json ':(exclude)src/test')
+          git show "$base:package.json" > "$RUNNER_TEMP/base-package.json"
+          deps=$(node scripts/dependencies-changed.js "$RUNNER_TEMP/base-package.json" package.json)
+
+          if [ -z "$changed" ] && [ "$deps" = "false" ]; then
+            echo "nothing here reaches Zapier, no version bump needed"
+            exit 0
+          fi
+
+          git show origin/master:package.json > "$RUNNER_TEMP/master-package.json"
+          master_version=$(node -p "JSON.parse(require('fs').readFileSync(process.env.RUNNER_TEMP + '/master-package.json', 'utf8')).version")
+          head_version=$(node -p "require('./package.json').version")
+
+          if [ "$master_version" = "$head_version" ]; then
+            echo "This branch changes code that reaches Zapier but leaves the version at $head_version." >&2
+            echo "Raise the minor version in package.json and add a matching '## <version>' entry to CHANGELOG.md." >&2
+            exit 1
+          fi
+
+          if [ "$(printf '%s\n%s\n' "$master_version" "$head_version" | sort -V | tail -1)" != "$head_version" ]; then
+            echo "Version $head_version is behind master, which is at $master_version. Rebase and bump again." >&2
+            exit 1
+          fi
+
+          if ! grep -q "^## ${head_version}\$" CHANGELOG.md; then
+            echo "CHANGELOG.md has no '## ${head_version}' entry, and Zapier reads that entry when the version is promoted." >&2
+            exit 1
+          fi
+
+          echo "version $master_version -> $head_version"

.github/workflows/release.yml

@@ -0,0 +1,82 @@
+name: Release
+
+on:
+  workflow_run:
+    workflows: ["CI"]
+    types: [completed]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: release
+  cancel-in-progress: false
+
+jobs:
+  release:
+    if: >-
+      (github.event_name == 'workflow_dispatch' && github.ref_name == 'master') ||
+      (github.event_name == 'workflow_run' && github.event.workflow_run.conclusion == 'success' &&
+      github.event.workflow_run.head_branch == 'master')
+    runs-on: ubuntu-latest
+    timeout-minutes: 45
+    outputs:
+      action: ${{ steps.state.outputs.action }}
+    steps:
+      - uses: actions/checkout@v7
+        with:
+          ref: ${{ github.event.workflow_run.head_sha || github.ref }}
+          fetch-depth: 0
+          persist-credentials: false
+
+      - uses: actions/setup-node@v7
+        with:
+          node-version-file: .nvmrc
+          cache: yarn
+
+      - name: Install
+        run: yarn install --frozen-lockfile
+
+      - name: Install the Zapier CLI
+        run: |
+          npm install --no-save --prefix "$RUNNER_TEMP/cli" zapier-platform-cli@19.1.0
+          echo "$RUNNER_TEMP/cli/node_modules/.bin" >> "$GITHUB_PATH"
+
+      - name: Ask Zapier what it holds
+        id: state
+        env:
+          ZAPIER_DEPLOY_KEY: ${{ secrets.ZAPIER_DEPLOY_KEY }}
+        run: |
+          zapier-platform versions --format=raw > "$RUNNER_TEMP/versions.json"
+          zapier-platform jobs --format=raw > "$RUNNER_TEMP/jobs.json"
+          jq -e . "$RUNNER_TEMP/jobs.json" >/dev/null 2>&1 || echo "[]" > "$RUNNER_TEMP/jobs.json"
+          node scripts/release-state.js "$RUNNER_TEMP/versions.json" "$RUNNER_TEMP/jobs.json" >> "$GITHUB_OUTPUT"
+
+      - name: Upload the version
+        if: steps.state.outputs.action == 'publish'
+        env:
+          ZAPIER_DEPLOY_KEY: ${{ secrets.ZAPIER_DEPLOY_KEY }}
+        run: yarn zapier-push
+
+      - name: Promote
+        if: steps.state.outputs.action == 'publish' || steps.state.outputs.action == 'promote'
+        env:
+          ZAPIER_DEPLOY_KEY: ${{ secrets.ZAPIER_DEPLOY_KEY }}
+          VERSION: ${{ steps.state.outputs.version }}
+        run: |
+          zapier-platform promote --yes "$VERSION"
+
+          for attempt in $(seq 1 60); do
+            stage=$(zapier-platform jobs --format=raw 2>/dev/null \
+              | jq -r --arg v "$VERSION" '[.[] | select(.job_kind == "promote" and .version_to == $v)] | last | .job_stage // empty' 2>/dev/null || true)
+            echo "attempt $attempt: ${stage:-no job yet}"
+            case "$stage" in
+              complete) exit 0 ;;
+              errored|aborted|paused) echo "promotion ended as $stage" >&2; exit 1 ;;
+            esac
+            sleep 20
+          done
+
+          echo "promotion did not finish within 20 minutes" >&2
+          exit 1

.nvmrc

@@ -1 +1 @@
-18.19.1
+22.23.2

README.md

@@ -11,7 +11,7 @@ yarn global add zapier-platform-cli
 yarn install
 ```
 
-Use Node 18 or newer, matching `package.json`. If you're running a newer version and don't have `nvm` set up, you can run `yarn install --ignore-engines` to disable the Node version check.
+Use Node 22 or newer, matching `package.json`. If you're running a newer version and don't have `nvm` set up, you can run `yarn install --ignore-engines` to disable the Node version check.
 
 ## Developing
 
@@ -22,14 +22,17 @@ For testing, save your envvars to `.env`. `.env.default` has the required variab
 
 ### Deployment
 
-Prerequisites:
+A release starts in your own pull request. Bump the minor version in `package.json` and add a
+matching `## <version>` entry to `CHANGELOG.md` alongside the code. CI fails the pull request if
+code that reaches Zapier changes without both.
 
-- Make sure you have updated the version number in `package.json`.
-- If updating Linear's app, you'll need to have access to Linear's Zapier account and generate a deploy key in `Settings > Deploy Keys`. You can then authenticate with the key using `zapier login --sso`.
+Merging to master uploads that version to Zapier and promotes it, so new Zaps get it.
 
-You can deploy the app to Zapier with `yarn zapier-push`. This will also run `yarn zapier-validate` before deploying.
+The workflow asks Zapier which versions it holds instead of assuming, so a release that never
+arrived is retried on the next push to master. Run it from the Actions tab when you want it sooner.
 
-After deploying, you'll need to manually promote the version to 'public' in Zapier's dashboard under `App > Manage > Versions`.
+Two things the release does not do. It does not move existing Zaps to the new version, so they
+keep running the version they were built on. It does not deprecate old versions.
 
 ## Forking
 

package.json

@@ -11,11 +11,11 @@
     "zapier-push": "npm run zapier-validate && zapier-platform push",
     "prepare": "npm run zapier-build && (husky install || true)",
     "pretest": "npm run zapier-build",
-    "test": "jest --passWithNoTests src/test",
+    "test": "jest --passWithNoTests src/test scripts",
     "prettier": "npx prettier --write ."
   },
   "engines": {
-    "node": ">=18.0.0",
+    "node": ">=22.0.0",
     "npm": ">=10.0.0"
   },
   "dependencies": {

scripts/dependencies-changed.js

@@ -0,0 +1,20 @@
+const fs = require("fs");
+
+const canonical = (dependencies = {}) =>
+  JSON.stringify(
+    Object.keys(dependencies)
+      .sort()
+      .map((name) => [name, dependencies[name]])
+  );
+
+const dependenciesChanged = (oldManifest, newManifest) =>
+  canonical(oldManifest.dependencies) !== canonical(newManifest.dependencies);
+
+const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+module.exports = { dependenciesChanged };
+
+if (require.main === module) {
+  const [oldFile, newFile] = process.argv.slice(2);
+  process.stdout.write(String(dependenciesChanged(read(oldFile), read(newFile))));
+}

scripts/dependencies-changed.test.js

@@ -0,0 +1,35 @@
+const { dependenciesChanged } = require("./dependencies-changed");
+
+const manifest = (dependencies) => ({ name: "linear-zapier", version: "4.15.0", dependencies });
+
+describe("dependenciesChanged", () => {
+  it("sees a version change", () => {
+    expect(dependenciesChanged(manifest({ lodash: "4.17.21" }), manifest({ lodash: "4.17.22" }))).toBe(true);
+  });
+
+  it("sees an added and a removed dependency", () => {
+    expect(dependenciesChanged(manifest({ lodash: "4.17.21" }), manifest({ lodash: "4.17.21", ky: "1.0.0" }))).toBe(
+      true
+    );
+    expect(dependenciesChanged(manifest({ lodash: "4.17.21", ky: "1.0.0" }), manifest({ lodash: "4.17.21" }))).toBe(
+      true
+    );
+  });
+
+  it("ignores key order", () => {
+    expect(
+      dependenciesChanged(manifest({ lodash: "4.17.21", ky: "1.0.0" }), manifest({ ky: "1.0.0", lodash: "4.17.21" }))
+    ).toBe(false);
+  });
+
+  it("ignores everything outside the dependencies block", () => {
+    const before = { ...manifest({ lodash: "4.17.21" }), devDependencies: { jest: "29.7.0" }, scripts: { test: "a" } };
+    const after = { ...manifest({ lodash: "4.17.21" }), devDependencies: { jest: "30.0.0" }, scripts: { test: "b" } };
+    expect(dependenciesChanged(before, after)).toBe(false);
+  });
+
+  it("treats a missing dependencies block as empty", () => {
+    expect(dependenciesChanged({ name: "x" }, { name: "x" })).toBe(false);
+    expect(dependenciesChanged({ name: "x" }, manifest({ lodash: "4.17.21" }))).toBe(true);
+  });
+});

scripts/release-state.js

@@ -0,0 +1,50 @@
+const fs = require("fs");
+const path = require("path");
+
+const ROOT = path.join(__dirname, "..");
+const PACKAGE_FILE = path.join(ROOT, "package.json");
+const FAILED_STAGES = ["aborted", "errored", "paused"];
+
+const releaseState = (version, versions, jobs) => {
+  if (!/^\d+\.\d+\.\d+$/.test(version)) {
+    return { action: "fail", reason: `unexpected version format: ${version}` };
+  }
+
+  const row = versions.find((v) => v.version === version);
+  if (!row) {
+    return { action: "publish" };
+  }
+  if (row.state === "deprecated") {
+    return { action: "fail", reason: `${version} is deprecated on Zapier.` };
+  }
+
+  const promotions = jobs.filter((job) => job.job_kind === "promote" && job.version_to === version);
+  if (promotions.some((job) => job.job_stage === "complete")) {
+    return { action: "none" };
+  }
+
+  const failed = promotions.find((job) => FAILED_STAGES.includes(job.job_stage));
+  if (failed) {
+    return { action: "promote", reason: `${version} promotion ended as ${failed.job_stage}.` };
+  }
+
+  return { action: "none" };
+};
+
+const read = (file) => JSON.parse(fs.readFileSync(file, "utf8"));
+
+module.exports = { releaseState };
+
+if (require.main === module) {
+  const [versionsFile, jobsFile] = process.argv.slice(2);
+  const { version } = read(PACKAGE_FILE);
+  const state = releaseState(version, read(versionsFile), read(jobsFile));
+
+  if (state.reason) {
+    process.stderr.write(`${state.reason}\n`);
+  }
+  if (state.action === "fail") {
+    process.exit(1);
+  }
+  process.stdout.write(`action=${state.action}\nversion=${version}\n`);
+}

scripts/release-state.test.js

@@ -0,0 +1,36 @@
+const { releaseState } = require("./release-state");
+
+describe("releaseState", () => {
+  it("publishes a version Zapier does not hold", () => {
+    expect(releaseState("4.16.0", [{ version: "4.15.0", state: "live" }], [])).toEqual({ action: "publish" });
+  });
+
+  it("does nothing when the version is live and no jobs exist", () => {
+    expect(releaseState("4.16.0", [{ version: "4.16.0", state: "live" }], [])).toEqual({ action: "none" });
+  });
+
+  it("fails on a deprecated version", () => {
+    const state = releaseState("4.16.0", [{ version: "4.16.0", state: "deprecated" }], []);
+    expect(state.action).toBe("fail");
+    expect(state.reason).toMatch(/deprecated/);
+  });
+
+  it("promotes again when the only promotion errored", () => {
+    const jobs = [{ job_kind: "promote", version_to: "4.16.0", job_stage: "errored" }];
+    const state = releaseState("4.16.0", [{ version: "4.16.0", state: "live" }], jobs);
+    expect(state.action).toBe("promote");
+    expect(state.reason).toMatch(/errored/);
+  });
+
+  it("does nothing when a later promotion completed", () => {
+    const jobs = [
+      { job_kind: "promote", version_to: "4.16.0", job_stage: "errored" },
+      { job_kind: "promote", version_to: "4.16.0", job_stage: "complete" },
+    ];
+    expect(releaseState("4.16.0", [{ version: "4.16.0", state: "live" }], jobs)).toEqual({ action: "none" });
+  });
+
+  it("fails on a version it does not understand", () => {
+    expect(releaseState("4.16", [], []).action).toBe("fail");
+  });
+});