From ef17292b4a4587cb5282e40d2ee96fff2001c2d4 Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 14:46:19 +0800 Subject: [PATCH 1/5] ci: add Cloudflare CI pipeline Add a Cloudflare CI pipeline in .cloudflare/ci/. It runs the build job and the Linux unit tests from test.yml in Cloudflare runners, and reports them as the cloudflare-ci/build and cloudflare-ci/unit-tests GitHub checks. Runs start manually with Wrangler, because Cloudflare CI has no GitHub triggers yet. - Type-check the pipeline in vp check through .cloudflare/ci/tsconfig.json and @cloudflare/workers-types. runner.d.ts adds step.runner(), which the published types do not include. - Include .cloudflare/ in the Fallow audit, with the pipeline as an entry point. - Document runs, deploys, and the runner environment in CONTRIBUTING.md. Co-Authored-By: Claude Opus 5.5 --- .cloudflare/ci/src/github.ts | 94 +++++++++++++++++++ .cloudflare/ci/src/index.ts | 166 +++++++++++++++++++++++++++++++++ .cloudflare/ci/src/runner.d.ts | 31 ++++++ .cloudflare/ci/src/scm.d.ts | 36 +++++++ .cloudflare/ci/tsconfig.json | 17 ++++ .cloudflare/ci/wrangler.jsonc | 30 ++++++ .fallowrc.json | 8 +- AGENTS.md | 1 + CONTRIBUTING.md | 60 +++++++++++- package.json | 1 + pnpm-lock.yaml | 8 ++ 11 files changed, 450 insertions(+), 2 deletions(-) create mode 100644 .cloudflare/ci/src/github.ts create mode 100644 .cloudflare/ci/src/index.ts create mode 100644 .cloudflare/ci/src/runner.d.ts create mode 100644 .cloudflare/ci/src/scm.d.ts create mode 100644 .cloudflare/ci/tsconfig.json create mode 100644 .cloudflare/ci/wrangler.jsonc diff --git a/.cloudflare/ci/src/github.ts b/.cloudflare/ci/src/github.ts new file mode 100644 index 0000000..06a92e5 --- /dev/null +++ b/.cloudflare/ci/src/github.ts @@ -0,0 +1,94 @@ +// Copied from the Cloudflare CI "Get started" guide. +// Runners cannot download code from GitHub yet, so this Worker serves it to them. +// Changes from the docs: the user-agent, SHA_PATTERN at module scope (e18e/prefer-static-regex), +// and hasValidSignature() split from serveSource() to keep Fallow complexity below its limit. +const GITHUB_HEADERS = { "user-agent": "setup-vp-ci" }; +const SHA_PATTERN = /^[0-9a-f]{40}$/; + +// Downloads the commit from SOURCE_URL into ./repo. +export const DOWNLOAD_SOURCE = [ + `node -e 'fetch(process.env.SOURCE_URL).then(async (r) => { if (!r.ok) throw new Error("download failed: " + r.status); require("fs").writeFileSync("source.tgz", Buffer.from(await r.arrayBuffer())); })'`, + "mkdir repo", + "tar xzf source.tgz -C repo --strip-components=1", +].join(" && "); + +// Get a new checkout in every step. Checkouts cannot be returned from a step. +export async function writeCheck(env: Env, sha: string, name: string, update: ScmCheckUpdate) { + const commit = await env.REPO.checkout({ sha }); + try { + return await commit.checks.write(name, update); + } finally { + commit[Symbol.dispose](); + } +} + +export async function commentOnPullRequest(env: Env, mr: number, body: string) { + const pullRequest = await env.REPO.checkout({ mr }); + try { + return await pullRequest.comments.write(body); + } finally { + pullRequest[Symbol.dispose](); + } +} + +// A pull request checkout does not include its commit SHA, so read it from GitHub. +export async function pullRequestHead(env: Env, mr: number) { + const outbound = await env.REPO.outbound(); + const response = await outbound.fetch( + `https://api.github.com/repos/${env.GITHUB_REPO}/commits/refs/pull/${mr}/head`, + { headers: GITHUB_HEADERS }, + ); + if (!response.ok) throw new Error(`GitHub returned ${response.status}`); + const { sha } = await response.json<{ sha: string }>(); + return sha; +} + +export async function sourceUrl(env: Env, sha: string) { + const expires = Math.floor(Date.now() / 1000) + 15 * 60; + const signature = await sign(env.SOURCE_SECRET, `${sha}:${expires}`); + return `${env.SOURCE_ORIGIN}/source/${sha}?expires=${expires}&signature=${signature}`; +} + +// Serves one commit's code to a runner, if the URL's signature is valid. +export async function serveSource(request: Request, env: Env) { + const url = new URL(request.url); + const [, route, sha = ""] = url.pathname.split("/"); + + if (route !== "source" || !SHA_PATTERN.test(sha)) { + return new Response("Not found", { status: 404 }); + } + if (!(await hasValidSignature(env, sha, url.searchParams))) { + return new Response("Forbidden", { status: 403 }); + } + + const outbound = await env.REPO.outbound(); + return outbound.fetch(`https://api.github.com/repos/${env.GITHUB_REPO}/tarball/${sha}`, { + headers: GITHUB_HEADERS, + }); +} + +async function hasValidSignature(env: Env, sha: string, params: URLSearchParams) { + const expires = Number(params.get("expires")); + const signature = params.get("signature") ?? ""; + const expected = await sign(env.SOURCE_SECRET, `${sha}:${expires}`); + const encoder = new TextEncoder(); + return ( + expires > Date.now() / 1000 && + signature.length === expected.length && + crypto.subtle.timingSafeEqual(encoder.encode(signature), encoder.encode(expected)) + ); +} + +async function sign(secret: string, message: string) { + const key = await crypto.subtle.importKey( + "raw", + new TextEncoder().encode(secret), + { name: "HMAC", hash: "SHA-256" }, + false, + ["sign"], + ); + const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message)); + return Array.from(new Uint8Array(signature), (byte) => byte.toString(16).padStart(2, "0")).join( + "", + ); +} diff --git a/.cloudflare/ci/src/index.ts b/.cloudflare/ci/src/index.ts new file mode 100644 index 0000000..5efb78c --- /dev/null +++ b/.cloudflare/ci/src/index.ts @@ -0,0 +1,166 @@ +import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers"; +import { + DOWNLOAD_SOURCE, + commentOnPullRequest, + pullRequestHead, + serveSource, + sourceUrl, + writeCheck, +} from "./github"; + +type Params = { sha?: string; mr?: number }; + +type Job = { name: string; command: string }; + +type RunResult = { passed: boolean; exitCode: number | null; summary?: string }; + +type JobResult = { check: string; passed: boolean; exitCode: number | null }; + +// The default image has Node.js 24, npm, and Corepack, but no pnpm or git. +// Corepack installs the pnpm version from package.json "packageManager". +// --ignore-scripts skips the root `prepare` script (`vp config`), which sets up +// Git hooks and fails without a git binary. The repo allows no dependency +// build scripts, so nothing else is skipped. +const INSTALL = [ + DOWNLOAD_SOURCE, + "cd repo", + "{ command -v corepack > /dev/null || npm install -g corepack; }", + "corepack enable", + "pnpm install --frozen-lockfile --ignore-scripts", +].join(" && "); + +const JOBS: Job[] = [ + { + // The "build" job in .github/workflows/test.yml. Runners get no Git + // history, so compare dist/ with a copy instead of `git diff`. + name: "build", + command: [ + INSTALL, + "pnpm run typecheck", + "pnpm run check", + "cp -R dist /tmp/dist-before", + "pnpm run build", + `{ diff -rq /tmp/dist-before dist || { echo "dist/ is out of date. Run 'vp run build' and commit."; exit 1; }; }`, + ].join(" && "), + }, + { + // The "Unit tests (ubuntu-latest)" job. Some tests read dist/, so build first. + // src/gitlab/workflow.test.ts runs the gitlab-e2e.yml script, which needs jq. + // GitHub-hosted runners include jq, but the default image does not. + name: "unit-tests", + command: [ + "apt-get update -qq", + "apt-get install -y -qq jq > /dev/null", + INSTALL, + "pnpm run build", + "pnpm run test", + ].join(" && "), + }, +]; + +// Checks run once. A timeout fails the step even with allowFailure. +const RUNNER_CONFIG = { retries: { limit: 0, delay: "1 second" }, timeout: "15 minutes" } as const; + +const RUNNER_ENV = { + CI: "true", + DEBIAN_FRONTEND: "noninteractive", + COREPACK_ENABLE_DOWNLOAD_PROMPT: "0", + NPM_CONFIG_UPDATE_NOTIFIER: "false", +}; + +// Bumped on each change, because `instances list` does not show which code ran. +const PIPELINE_VERSION = "2026-11-17.4"; + +export class CI extends WorkflowEntrypoint { + async run(event: WorkflowEvent, step: WorkflowStep) { + const { env } = this; + const { mr } = event.payload; + + const sha = await step.do("resolve commit", async () => { + if (event.payload.sha) return event.payload.sha; + if (!mr) throw new Error("Pass a sha or an mr"); + return pullRequestHead(env, mr); + }); + + const source = await step.do("sign source URL", { sensitive: "output" }, () => + sourceUrl(env, sha), + ); + + const results = await Promise.all(JOBS.map((job) => runJob(env, step, sha, source, job))); + + if (mr) { + await step.do("comment on pull request", () => + commentOnPullRequest(env, mr, formatComment(sha, results)), + ); + } + + const passed = results.every((result) => result.passed); + return { conclusion: passed ? "passed" : "failed", sha, version: PIPELINE_VERSION, results }; + } +} + +// Runs one job in a runner and reports it as a GitHub check. +async function runJob( + env: Env, + step: WorkflowStep, + sha: string, + source: string, + { name, command }: Job, +): Promise { + const check = `cloudflare-ci/${name}`; + await step.do(`start ${name}`, () => writeCheck(env, sha, check, { status: "in_progress" })); + + const result = await runCommand(step, name, command, source); + + await step.do(`complete ${name}`, () => + writeCheck(env, sha, check, { + status: "completed", + conclusion: result.passed ? "success" : "failure", + title: result.passed ? "Passed" : `Failed (${failureReason(result.exitCode)})`, + summary: result.summary, + }), + ); + return { check, passed: result.passed, exitCode: result.exitCode }; +} + +// Timeouts and container errors throw, even with allowFailure. Catch them, so +// that the caller can fail the check and it does not stay in progress. +async function runCommand( + step: WorkflowStep, + name: string, + command: string, + source: string, +): Promise { + try { + const run = await step.runner(name, RUNNER_CONFIG, { + command, + env: { ...RUNNER_ENV, SOURCE_URL: source }, + instanceSize: "standard-3", + allowFailure: true, + }); + if (run.exitCode === 0) return { passed: true, exitCode: 0 }; + // The runner returns one combined log stream: { data, truncated }. + return { + passed: false, + exitCode: run.exitCode, + summary: "```\n" + run.logs.data.slice(-6000) + "\n```", + }; + } catch (error) { + const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error); + return { passed: false, exitCode: null, summary: message }; + } +} + +function failureReason(exitCode: number | null) { + return exitCode === null ? "runner error" : `exit ${exitCode}`; +} + +function formatComment(sha: string, results: JobResult[]) { + const lines = results.map( + ({ check, passed, exitCode }) => + `- ${passed ? "✅" : "❌"} \`${check}\`` + (passed ? "" : ` (${failureReason(exitCode)})`), + ); + return [`Cloudflare CI on \`${sha.slice(0, 7)}\`:`, ...lines].join("\n"); +} + +export default { fetch: serveSource } satisfies ExportedHandler; diff --git a/.cloudflare/ci/src/runner.d.ts b/.cloudflare/ci/src/runner.d.ts new file mode 100644 index 0000000..57cabf4 --- /dev/null +++ b/.cloudflare/ci/src/runner.d.ts @@ -0,0 +1,31 @@ +// Types for step.runner(). @cloudflare/workers-types does not include it yet. +// The result shape comes from the runtime. The docs show `logs.stdout` and +// `logs.stderr`, but the runtime returns one combined stream in `logs`. +export {}; + +declare module "cloudflare:workers" { + interface WorkflowStep { + runner(name: string, options: RunnerOptions): Promise; + runner(name: string, config: WorkflowStepConfig, options: RunnerOptions): Promise; + } + + /** A saved output of an earlier runner in the same run. */ + type RunnerOutput = object; + + interface RunnerOptions { + /** A shell script, run with /bin/sh in /workspace as root. */ + command: string; + inputs?: RunnerOutput[]; + outputs?: Record; + env?: Record; + image?: { repository: string; digest: string }; + instanceSize?: "lite" | "basic" | "standard-1" | "standard-2" | "standard-3" | "standard-4"; + allowFailure?: boolean; + } + + interface RunnerResult { + exitCode: number; + logs: { data: string; truncated: boolean }; + outputs: Record; + } +} diff --git a/.cloudflare/ci/src/scm.d.ts b/.cloudflare/ci/src/scm.d.ts new file mode 100644 index 0000000..fceea58 --- /dev/null +++ b/.cloudflare/ci/src/scm.d.ts @@ -0,0 +1,36 @@ +// Copied from the Cloudflare CI "Get started" guide. +// Wrangler does not generate types for the scm binding yet. +interface ScmRepository { + checkout(target: { sha: string }): Promise; + checkout(target: { mr: number }): Promise; + outbound(): Promise; +} + +interface ScmCheckout { + readonly checks: { + write(name: string, update: ScmCheckUpdate): Promise<{ checkRunId: number; url: string }>; + }; + readFile(file: { path: string }): Promise; +} + +interface ScmCheckUpdate { + status: "queued" | "in_progress" | "completed"; + conclusion?: "success" | "failure" | "neutral" | "cancelled"; + title?: string; + summary?: string; + detailsUrl?: string; +} + +interface ScmMergeRequestCheckout extends ScmCheckout { + readonly comments: { + write(body: string): Promise<{ commentId: number; url: string }>; + }; +} + +interface Env { + REPO: ScmRepository; + CI_WORKFLOW: Workflow; + GITHUB_REPO: string; + SOURCE_ORIGIN: string; + SOURCE_SECRET: string; +} diff --git a/.cloudflare/ci/tsconfig.json b/.cloudflare/ci/tsconfig.json new file mode 100644 index 0000000..76ac972 --- /dev/null +++ b/.cloudflare/ci/tsconfig.json @@ -0,0 +1,17 @@ +{ + "compilerOptions": { + "target": "ES2022", + "module": "ES2022", + "moduleResolution": "Bundler", + "lib": ["ESNext"], + "types": ["@cloudflare/workers-types"], + "strict": true, + "noEmit": true, + "skipLibCheck": true, + "noUnusedLocals": true, + "noUnusedParameters": true, + "verbatimModuleSyntax": true, + "isolatedModules": true + }, + "include": ["src/**/*"] +} diff --git a/.cloudflare/ci/wrangler.jsonc b/.cloudflare/ci/wrangler.jsonc new file mode 100644 index 0000000..817a649 --- /dev/null +++ b/.cloudflare/ci/wrangler.jsonc @@ -0,0 +1,30 @@ +{ + // Cloudflare CI pipeline for this repository. See CONTRIBUTING.md#cloudflare-ci. + "name": "setup-vp-ci", + "main": "src/index.ts", + "compatibility_date": "2026-11-01", + "workflows": [{ "name": "setup-vp-ci", "binding": "CI_WORKFLOW", "class_name": "CI" }], + "vars": { + "GITHUB_REPO": "voidzero-dev/setup-vp", + // The Worker's workers.dev URL. Runners download the source from it. + "SOURCE_ORIGIN": "https://setup-vp-ci.voidzero-docs.workers.dev", + }, + "unsafe": { + "bindings": [ + { + "type": "scm", + "name": "REPO", + "provider": "github", + "repo": "voidzero-dev/setup-vp", + "scopes": [ + "contents:read", + "checks:write", + "comments:write", + "merge_requests:read", + "outbound:read", + ], + }, + ], + }, + "observability": { "enabled": true }, +} diff --git a/.fallowrc.json b/.fallowrc.json index 8894caf..0d56a53 100644 --- a/.fallowrc.json +++ b/.fallowrc.json @@ -1,5 +1,11 @@ { "$schema": "./node_modules/fallow/schema.json", - "entry": ["src/index.ts", "src/gitlab/index.ts", "src/azure/index.ts"], + "entry": [ + "src/index.ts", + "src/gitlab/index.ts", + "src/azure/index.ts", + ".cloudflare/ci/src/index.ts" + ], + "ignorePatterns": ["!.cloudflare/**"], "ignoreDependencies": ["@e18e/eslint-plugin"] } diff --git a/AGENTS.md b/AGENTS.md index b3d7395..744c605 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -8,6 +8,7 @@ setup-vp installs [Vite+](https://viteplus.dev) (`vp`) through GitHub Actions, G - For GitHub Actions behavior, start with `action.yml` and `src/index.ts`; input parsing and schemas live in `src/inputs.ts` and `src/types.ts`. - For GitLab or Azure behavior, start with `src/gitlab/index.ts` or `src/azure/index.ts` and the corresponding templates and bootstrap scripts in `gitlab/` or `azure/`. See [Integration Design](CONTRIBUTING.md#integration-design) for the design references. - For behavior shared across integrations, start with `src/ci/` and the corresponding adapters under `src/`, `src/gitlab/`, and `src/azure/`. +- For the Cloudflare CI pipeline, start with `.cloudflare/ci/src/index.ts` and follow [Cloudflare CI](CONTRIBUTING.md#cloudflare-ci). Its jobs mirror the `build` and Linux unit test jobs in `.github/workflows/test.yml`. ## Implementation Constraints diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 67ab93a..7c1dd7c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -53,7 +53,7 @@ The action uses the exact `fallow` version in `package.json`. After `vp install` vp exec fallow audit --base origin/main ``` -[`.fallowrc.json`](.fallowrc.json) declares the three runtime entry points. Fallow excludes generated files under `dist/` by default. Results appear in annotations, CI logs, and the job summary. The workflow does not write PR comments. +[`.fallowrc.json`](.fallowrc.json) declares the three runtime entry points and the [Cloudflare CI](#cloudflare-ci) pipeline entry point. Fallow skips hidden directories by default, so the configuration includes `.cloudflare/` explicitly. Fallow excludes generated files under `dist/` by default. Results appear in annotations, CI logs, and the job summary. The workflow does not write PR comments. ## Integration Design @@ -108,6 +108,64 @@ For a standalone run, omit `pull_request`. Set `setup_ref` to an exact commit SH Pushes, merge queue commits, merges, and release tags do not automatically start GitLab pipelines. Release PRs must pass the full suite on their current head commit before merging; follow the [release procedure](#releasing). +## Cloudflare CI + +[`.cloudflare/ci/`](.cloudflare/ci/) contains a Cloudflare CI pipeline. Cloudflare CI is in preview. The pipeline runs two jobs from [`test.yml`](.github/workflows/test.yml) in Cloudflare runners and reports them as GitHub checks: + +- `cloudflare-ci/build`: `typecheck`, `check`, `build`, and a check that `dist/` is up to date. +- `cloudflare-ci/unit-tests`: `build`, then `test`. + +The other jobs in `test.yml` run the action through `uses: ./`, so they stay on GitHub Actions. The Cloudflare CI checks are not required checks. + +The pipeline is a Workflow in the `setup-vp-ci` Worker of the `VoidZero-docs` Cloudflare account. The deployed version runs for every branch. A change under `.cloudflare/ci/` takes effect only after a deploy, so a PR that changes the pipeline still runs the deployed version. + +To use Wrangler, you need access to the `VoidZero-docs` account. Run `npx wrangler@4.163.0 login` first. + +### Start a Run + +GitHub triggers are not available yet, so start each run with Wrangler: + +```bash +cd .cloudflare/ci + +# A pull request: posts the checks and a new PR comment. +npx wrangler@4.163.0 workflows trigger setup-vp-ci '{"mr":123}' + +# A commit (full SHA): posts or updates the checks, with no comment. +npx wrangler@4.163.0 workflows trigger setup-vp-ci "{\"sha\":\"$(git rev-parse HEAD)\"}" + +# Follow runs. +npx wrangler@4.163.0 workflows instances list setup-vp-ci +npx wrangler@4.163.0 workflows instances describe setup-vp-ci +``` + +Each `mr` run posts a new PR comment. To run a PR again without another comment, start the run with the PR head SHA. A failed check shows the last 6,000 characters of its log in the check summary. + +### Change the Pipeline + +1. Edit the files in `.cloudflare/ci/src/`, and increase `PIPELINE_VERSION` in `index.ts`. +2. Run `vp check`. It formats, lints, and type-checks the pipeline with [`.cloudflare/ci/tsconfig.json`](.cloudflare/ci/tsconfig.json) and `@cloudflare/workers-types`. +3. After the change merges, deploy from `main`: + + ```bash + cd .cloudflare/ci + npx wrangler@4.163.0 deploy + ``` + +4. Read `output.version` in the result of the next run. A run that starts in the first minutes after a deploy can still use the previous version. The plain `describe` output does not include the return value, so use `--json`: + + ```bash + npx wrangler@4.163.0 workflows instances describe setup-vp-ci --json --step-output=false + ``` + +### Runner Environment + +- The default runner image has Node.js 24, npm, and Corepack, but no `git`, `jq`, or `pnpm`. GitHub CI uses `lts/*` from `.node-version`. +- The install uses `pnpm install --ignore-scripts`, because the root `prepare` script (`vp config`) fails without `git`. The repository allows no dependency build scripts, so the flag skips nothing else. +- The `unit-tests` runner installs `jq` with `apt-get`, because `src/gitlab/workflow.test.ts` runs the GitLab E2E workflow script, which uses `jq`. +- Runners cannot check out code from GitHub yet. The Worker serves each commit as a tarball through a signed URL, so runners have no Git history. `SOURCE_SECRET` signs the URLs. To replace it, run `openssl rand -hex 32 | npx wrangler@4.163.0 secret put SOURCE_SECRET` in `.cloudflare/ci/`. +- `@cloudflare/workers-types` does not include `step.runner()`. [`runner.d.ts`](.cloudflare/ci/src/runner.d.ts) declares the result that the runtime returns, `logs: { data, truncated }`. The Cloudflare CI docs show `logs.stdout` and `logs.stderr` instead. + ## Dependency Updates For same-repository PRs with the `needs-bundle-rebuild` label, [the build workflow](.github/workflows/rebuild-bundle.yml) builds the exact PR commit with read-only access. After a successful build, a maintainer reviews its commit and dispatches [the publisher](.github/workflows/publish-bundle.yml) on `main` with that build's run ID: diff --git a/package.json b/package.json index 312dc23..0e07c66 100644 --- a/package.json +++ b/package.json @@ -22,6 +22,7 @@ "zod": "^4.0.0" }, "devDependencies": { + "@cloudflare/workers-types": "^5.20261116.1", "@e18e/eslint-plugin": "^0.8.1", "@types/node": "^24.0.0", "fallow": "3.33.1", diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml index d76ec65..f37fae9 100644 --- a/pnpm-lock.yaml +++ b/pnpm-lock.yaml @@ -200,6 +200,9 @@ importers: specifier: ^4.0.0 version: 4.6.7 devDependencies: + '@cloudflare/workers-types': + specifier: ^5.20261116.1 + version: 5.20261116.1 '@e18e/eslint-plugin': specifier: ^0.8.1 version: 0.8.1(oxlint@1.88.0(oxlint-tsgolint@7.0.2004)(vite-plus@1.3.0(@types/node@24.12.2)(@vitest/ui@5.0.5)(typescript@7.0.2)(yaml@2.9.1))) @@ -313,6 +316,9 @@ packages: '@blazediff/core@1.10.0': resolution: {integrity: sha512-AOQff0zgR7cGsZL+4E7hVkmujoPUpm0J9xzWGWZj5wCjd3gmxESXAPfKyuzs93VdpQNFhHlBhfOjrcZ+XTERtQ==} + '@cloudflare/workers-types@5.20261116.1': + resolution: {integrity: sha512-bym4dNT9Hnm+goedLTTTH85T6S4wOJJaOpKgk9MlEGU18/JKsChN+wHvSWUAIy5YVSm6LnuaUu3d3N4K0m8Dtg==} + '@e18e/eslint-plugin@0.8.1': resolution: {integrity: sha512-OV3T7l0r52/IglskdAuoO+BJyzsCs7AcIHpwpBMlIMO0+3RHskM2h5MuHdLuesIhSRhwCURGMKtp/XwnfXrfxg==} peerDependencies: @@ -1684,6 +1690,8 @@ snapshots: '@blazediff/core@1.10.0': {} + '@cloudflare/workers-types@5.20261116.1': {} + '@e18e/eslint-plugin@0.8.1(oxlint@1.88.0(oxlint-tsgolint@7.0.2004)(vite-plus@1.3.0(@types/node@24.12.2)(@vitest/ui@5.0.5)(typescript@7.0.2)(yaml@2.9.1)))': dependencies: empathic: 2.1.0 From f6fcb67251ee41116ca5a7805470836e05b816e6 Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 14:55:59 +0800 Subject: [PATCH 2/5] ci: link Cloudflare CI checks to the run and keep the runner log Each check links to its run in the Cloudflare dashboard and shows the runner log, up to the last 16 KiB, in its summary. Jobs run in timeout 14m, so a hung job keeps its log, and NO_COLOR removes ANSI codes from the log. Co-Authored-By: Claude Opus 5.5 --- .cloudflare/ci/src/index.ts | 86 ++++++++++++++++++++++++----------- .cloudflare/ci/src/scm.d.ts | 2 + .cloudflare/ci/wrangler.jsonc | 2 + CONTRIBUTING.md | 14 +++++- 4 files changed, 77 insertions(+), 27 deletions(-) diff --git a/.cloudflare/ci/src/index.ts b/.cloudflare/ci/src/index.ts index 5efb78c..c447268 100644 --- a/.cloudflare/ci/src/index.ts +++ b/.cloudflare/ci/src/index.ts @@ -12,7 +12,15 @@ type Params = { sha?: string; mr?: number }; type Job = { name: string; command: string }; -type RunResult = { passed: boolean; exitCode: number | null; summary?: string }; +type RunContext = { env: Env; step: WorkflowStep; sha: string; source: string; runUrl: string }; + +type RunResult = { + passed: boolean; + exitCode: number | null; + log?: string; + truncated?: boolean; + error?: string; +}; type JobResult = { check: string; passed: boolean; exitCode: number | null }; @@ -58,23 +66,34 @@ const JOBS: Job[] = [ }, ]; -// Checks run once. A timeout fails the step even with allowFailure. +// Checks run once. A step timeout fails the step even with allowFailure, and +// the step loses its logs. const RUNNER_CONFIG = { retries: { limit: 0, delay: "1 second" }, timeout: "15 minutes" } as const; +// Stop each command before the step timeout, so that its logs are kept. +// `timeout` exits with 124 when it stops the command. +const COMMAND_TIMEOUT_MINUTES = 14; +const TIMEOUT_EXIT_CODE = 124; + const RUNNER_ENV = { CI: "true", DEBIAN_FRONTEND: "noninteractive", COREPACK_ENABLE_DOWNLOAD_PROMPT: "0", NPM_CONFIG_UPDATE_NOTIFIER: "false", + // Keep ANSI color codes out of the log in the check summary. + NO_COLOR: "1", + FORCE_COLOR: "0", }; // Bumped on each change, because `instances list` does not show which code ran. -const PIPELINE_VERSION = "2026-11-17.4"; +const PIPELINE_VERSION = "2026-11-17.5"; export class CI extends WorkflowEntrypoint { async run(event: WorkflowEvent, step: WorkflowStep) { const { env } = this; const { mr } = event.payload; + // The checks and the PR comment link to this run in the Cloudflare dashboard. + const runUrl = env.RUN_URL_BASE + event.instanceId; const sha = await step.do("resolve commit", async () => { if (event.payload.sha) return event.payload.sha; @@ -86,11 +105,12 @@ export class CI extends WorkflowEntrypoint { sourceUrl(env, sha), ); - const results = await Promise.all(JOBS.map((job) => runJob(env, step, sha, source, job))); + const context: RunContext = { env, step, sha, source, runUrl }; + const results = await Promise.all(JOBS.map((job) => runJob(context, job))); if (mr) { await step.do("comment on pull request", () => - commentOnPullRequest(env, mr, formatComment(sha, results)), + commentOnPullRequest(env, mr, formatComment(context, results)), ); } @@ -100,31 +120,29 @@ export class CI extends WorkflowEntrypoint { } // Runs one job in a runner and reports it as a GitHub check. -async function runJob( - env: Env, - step: WorkflowStep, - sha: string, - source: string, - { name, command }: Job, -): Promise { +async function runJob(context: RunContext, { name, command }: Job): Promise { + const { env, step, sha, runUrl } = context; const check = `cloudflare-ci/${name}`; - await step.do(`start ${name}`, () => writeCheck(env, sha, check, { status: "in_progress" })); + await step.do(`start ${name}`, () => + writeCheck(env, sha, check, { status: "in_progress", detailsUrl: runUrl }), + ); - const result = await runCommand(step, name, command, source); + const result = await runCommand(step, name, command, context.source); await step.do(`complete ${name}`, () => writeCheck(env, sha, check, { status: "completed", conclusion: result.passed ? "success" : "failure", title: result.passed ? "Passed" : `Failed (${failureReason(result.exitCode)})`, - summary: result.summary, + summary: formatSummary(result), + detailsUrl: runUrl, }), ); return { check, passed: result.passed, exitCode: result.exitCode }; } -// Timeouts and container errors throw, even with allowFailure. Catch them, so -// that the caller can fail the check and it does not stay in progress. +// Step timeouts and container errors throw, even with allowFailure. Catch them, +// so that the caller can fail the check and it does not stay in progress. async function runCommand( step: WorkflowStep, name: string, @@ -133,34 +151,50 @@ async function runCommand( ): Promise { try { const run = await step.runner(name, RUNNER_CONFIG, { - command, - env: { ...RUNNER_ENV, SOURCE_URL: source }, + // JOB_COMMAND keeps the quotes in the job command intact inside `sh -c`. + command: `timeout ${COMMAND_TIMEOUT_MINUTES}m sh -c "$JOB_COMMAND"`, + env: { ...RUNNER_ENV, SOURCE_URL: source, JOB_COMMAND: command }, instanceSize: "standard-3", allowFailure: true, }); - if (run.exitCode === 0) return { passed: true, exitCode: 0 }; // The runner returns one combined log stream: { data, truncated }. return { - passed: false, + passed: run.exitCode === 0, exitCode: run.exitCode, - summary: "```\n" + run.logs.data.slice(-6000) + "\n```", + log: run.logs.data, + truncated: run.logs.truncated, }; } catch (error) { const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error); - return { passed: false, exitCode: null, summary: message }; + return { passed: false, exitCode: null, error: message }; } } function failureReason(exitCode: number | null) { - return exitCode === null ? "runner error" : `exit ${exitCode}`; + if (exitCode === null) return "runner error"; + if (exitCode === TIMEOUT_EXIT_CODE) return `timed out after ${COMMAND_TIMEOUT_MINUTES} minutes`; + return `exit ${exitCode}`; +} + +// The runner keeps at most 16 KiB of log, which fits in a check summary +// (65,535 characters). The four-backtick fence allows ``` in the log. +function formatSummary({ log, truncated, error }: RunResult) { + if (error !== undefined) return error; + const heading = truncated ? "The last 16 KiB of the runner log:" : "The runner log:"; + return `${heading}\n\n\`\`\`\`text\n${log ?? ""}\n\`\`\`\``; } -function formatComment(sha: string, results: JobResult[]) { +function formatComment({ sha, runUrl }: RunContext, results: JobResult[]) { const lines = results.map( ({ check, passed, exitCode }) => `- ${passed ? "✅" : "❌"} \`${check}\`` + (passed ? "" : ` (${failureReason(exitCode)})`), ); - return [`Cloudflare CI on \`${sha.slice(0, 7)}\`:`, ...lines].join("\n"); + return [ + `Cloudflare CI on \`${sha.slice(0, 7)}\`:`, + ...lines, + "", + `[View the run in the Cloudflare dashboard](${runUrl})`, + ].join("\n"); } export default { fetch: serveSource } satisfies ExportedHandler; diff --git a/.cloudflare/ci/src/scm.d.ts b/.cloudflare/ci/src/scm.d.ts index fceea58..c1757fc 100644 --- a/.cloudflare/ci/src/scm.d.ts +++ b/.cloudflare/ci/src/scm.d.ts @@ -1,5 +1,6 @@ // Copied from the Cloudflare CI "Get started" guide. // Wrangler does not generate types for the scm binding yet. +// Changes from the docs: RUN_URL_BASE in Env. interface ScmRepository { checkout(target: { sha: string }): Promise; checkout(target: { mr: number }): Promise; @@ -33,4 +34,5 @@ interface Env { GITHUB_REPO: string; SOURCE_ORIGIN: string; SOURCE_SECRET: string; + RUN_URL_BASE: string; } diff --git a/.cloudflare/ci/wrangler.jsonc b/.cloudflare/ci/wrangler.jsonc index 817a649..cd73735 100644 --- a/.cloudflare/ci/wrangler.jsonc +++ b/.cloudflare/ci/wrangler.jsonc @@ -8,6 +8,8 @@ "GITHUB_REPO": "voidzero-dev/setup-vp", // The Worker's workers.dev URL. Runners download the source from it. "SOURCE_ORIGIN": "https://setup-vp-ci.voidzero-docs.workers.dev", + // The dashboard URL of a run, without the instance ID. Checks link to it. + "RUN_URL_BASE": "https://dash.cloudflare.com/f8b59a295069bd81a0f256b7012f2c53/workers/workflows/setup-vp-ci/instance/", }, "unsafe": { "bindings": [ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7c1dd7c..b6f8f78 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -139,7 +139,19 @@ npx wrangler@4.163.0 workflows instances list setup-vp-ci npx wrangler@4.163.0 workflows instances describe setup-vp-ci ``` -Each `mr` run posts a new PR comment. To run a PR again without another comment, start the run with the PR head SHA. A failed check shows the last 6,000 characters of its log in the check summary. +Each `mr` run posts a new PR comment. To run a PR again without another comment, start the run with the PR head SHA. + +### Read Logs + +- Each check summary shows the runner log, up to its last 16 KiB. The runner keeps no more than that. +- The **Details** link of each check and the link in the PR comment open the run in the Cloudflare dashboard. Only members of the `VoidZero-docs` account can open it. +- `describe` and `describe --json` cut each step output to about 1 KiB. Use them for the step status and the run error, not for logs. +- Each job runs in `timeout 14m`. A job that hangs stops with exit code 124 and keeps its log. The 15-minute step timeout would lose the log. +- To run a failed job again without the other steps before it, restart the run from that job's step. The restart also runs every later step, which includes the PR comment of an `mr` run: + + ```bash + npx wrangler@4.163.0 workflows instances restart setup-vp-ci --from-step-name "unit-tests" + ``` ### Change the Pipeline From 2e6824d6326e6804eafe02a65218775a75a566eb Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 15:11:45 +0800 Subject: [PATCH 3/5] ci: link each check in the Cloudflare CI comment to its check page The check page on the PR shows the runner log. The dashboard link stays at the end of the comment. Co-Authored-By: Claude Opus 5.5 --- .cloudflare/ci/src/index.ts | 19 +++++++++++-------- CONTRIBUTING.md | 3 ++- 2 files changed, 13 insertions(+), 9 deletions(-) diff --git a/.cloudflare/ci/src/index.ts b/.cloudflare/ci/src/index.ts index c447268..d6778fc 100644 --- a/.cloudflare/ci/src/index.ts +++ b/.cloudflare/ci/src/index.ts @@ -22,7 +22,7 @@ type RunResult = { error?: string; }; -type JobResult = { check: string; passed: boolean; exitCode: number | null }; +type JobResult = { check: string; passed: boolean; exitCode: number | null; checkRunId: number }; // The default image has Node.js 24, npm, and Corepack, but no pnpm or git. // Corepack installs the pnpm version from package.json "packageManager". @@ -86,7 +86,7 @@ const RUNNER_ENV = { }; // Bumped on each change, because `instances list` does not show which code ran. -const PIPELINE_VERSION = "2026-11-17.5"; +const PIPELINE_VERSION = "2026-11-17.6"; export class CI extends WorkflowEntrypoint { async run(event: WorkflowEvent, step: WorkflowStep) { @@ -110,7 +110,7 @@ export class CI extends WorkflowEntrypoint { if (mr) { await step.do("comment on pull request", () => - commentOnPullRequest(env, mr, formatComment(context, results)), + commentOnPullRequest(env, mr, formatComment(context, mr, results)), ); } @@ -129,7 +129,7 @@ async function runJob(context: RunContext, { name, command }: Job): Promise + const { checkRunId } = await step.do(`complete ${name}`, () => writeCheck(env, sha, check, { status: "completed", conclusion: result.passed ? "success" : "failure", @@ -138,7 +138,7 @@ async function runJob(context: RunContext, { name, command }: Job): Promise - `- ${passed ? "✅" : "❌"} \`${check}\`` + (passed ? "" : ` (${failureReason(exitCode)})`), + ({ check, passed, exitCode, checkRunId }) => + `- ${passed ? "✅" : "❌"} [\`${check}\`](${checksUrl}?check_run_id=${checkRunId})` + + (passed ? "" : ` (${failureReason(exitCode)})`), ); return [ `Cloudflare CI on \`${sha.slice(0, 7)}\`:`, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b6f8f78..a7ffdba 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -144,7 +144,8 @@ Each `mr` run posts a new PR comment. To run a PR again without another comment, ### Read Logs - Each check summary shows the runner log, up to its last 16 KiB. The runner keeps no more than that. -- The **Details** link of each check and the link in the PR comment open the run in the Cloudflare dashboard. Only members of the `VoidZero-docs` account can open it. +- In the PR comment, each check name links to its check page on the PR, which shows the log. +- The **Details** link of each check and the last link in the PR comment open the run in the Cloudflare dashboard. Only members of the `VoidZero-docs` account can open it. - `describe` and `describe --json` cut each step output to about 1 KiB. Use them for the step status and the run error, not for logs. - Each job runs in `timeout 14m`. A job that hangs stops with exit code 124 and keeps its log. The 15-minute step timeout would lose the log. - To run a failed job again without the other steps before it, restart the run from that job's step. The restart also runs every later step, which includes the PR comment of an `mr` run: From 4abd4a1ed416d12612abeec2e9d9c7a2878c4e4c Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Fri, 20 Nov 2026 11:58:02 +0800 Subject: [PATCH 4/5] ci: check out with git and cache the Cloudflare CI install Use the managed workflows/node image, which has git and jq. A checkout step fetches the commit from GitHub, because the repository is public, and the build job compares dist/ with git diff, the same as test.yml. This removes the source server, its signed URLs, SOURCE_SECRET, and the workers.dev URL. An install step gets only package.json, pnpm-lock.yaml, and pnpm-workspace.yaml, and uses the runner cache. The jobs restore the checkout and node_modules from it, so a run skips the install while those files do not change. A pull request comment is now posted only when a check fails. Co-Authored-By: Claude Opus 5.5 --- .cloudflare/ci/src/github.ts | 65 +-------- .cloudflare/ci/src/index.ts | 235 ++++++++++++++++++++++----------- .cloudflare/ci/src/runner.d.ts | 36 ++++- .cloudflare/ci/src/scm.d.ts | 4 +- .cloudflare/ci/wrangler.jsonc | 5 +- CONTRIBUTING.md | 15 ++- 6 files changed, 202 insertions(+), 158 deletions(-) diff --git a/.cloudflare/ci/src/github.ts b/.cloudflare/ci/src/github.ts index 06a92e5..6f6aeec 100644 --- a/.cloudflare/ci/src/github.ts +++ b/.cloudflare/ci/src/github.ts @@ -1,16 +1,7 @@ -// Copied from the Cloudflare CI "Get started" guide. -// Runners cannot download code from GitHub yet, so this Worker serves it to them. -// Changes from the docs: the user-agent, SHA_PATTERN at module scope (e18e/prefer-static-regex), -// and hasValidSignature() split from serveSource() to keep Fallow complexity below its limit. +// Based on the helpers in the Cloudflare CI "Get started" guide. +// Changes from the docs: the user-agent, and no source server, because runners +// check out the public repository with git. const GITHUB_HEADERS = { "user-agent": "setup-vp-ci" }; -const SHA_PATTERN = /^[0-9a-f]{40}$/; - -// Downloads the commit from SOURCE_URL into ./repo. -export const DOWNLOAD_SOURCE = [ - `node -e 'fetch(process.env.SOURCE_URL).then(async (r) => { if (!r.ok) throw new Error("download failed: " + r.status); require("fs").writeFileSync("source.tgz", Buffer.from(await r.arrayBuffer())); })'`, - "mkdir repo", - "tar xzf source.tgz -C repo --strip-components=1", -].join(" && "); // Get a new checkout in every step. Checkouts cannot be returned from a step. export async function writeCheck(env: Env, sha: string, name: string, update: ScmCheckUpdate) { @@ -42,53 +33,3 @@ export async function pullRequestHead(env: Env, mr: number) { const { sha } = await response.json<{ sha: string }>(); return sha; } - -export async function sourceUrl(env: Env, sha: string) { - const expires = Math.floor(Date.now() / 1000) + 15 * 60; - const signature = await sign(env.SOURCE_SECRET, `${sha}:${expires}`); - return `${env.SOURCE_ORIGIN}/source/${sha}?expires=${expires}&signature=${signature}`; -} - -// Serves one commit's code to a runner, if the URL's signature is valid. -export async function serveSource(request: Request, env: Env) { - const url = new URL(request.url); - const [, route, sha = ""] = url.pathname.split("/"); - - if (route !== "source" || !SHA_PATTERN.test(sha)) { - return new Response("Not found", { status: 404 }); - } - if (!(await hasValidSignature(env, sha, url.searchParams))) { - return new Response("Forbidden", { status: 403 }); - } - - const outbound = await env.REPO.outbound(); - return outbound.fetch(`https://api.github.com/repos/${env.GITHUB_REPO}/tarball/${sha}`, { - headers: GITHUB_HEADERS, - }); -} - -async function hasValidSignature(env: Env, sha: string, params: URLSearchParams) { - const expires = Number(params.get("expires")); - const signature = params.get("signature") ?? ""; - const expected = await sign(env.SOURCE_SECRET, `${sha}:${expires}`); - const encoder = new TextEncoder(); - return ( - expires > Date.now() / 1000 && - signature.length === expected.length && - crypto.subtle.timingSafeEqual(encoder.encode(signature), encoder.encode(expected)) - ); -} - -async function sign(secret: string, message: string) { - const key = await crypto.subtle.importKey( - "raw", - new TextEncoder().encode(secret), - { name: "HMAC", hash: "SHA-256" }, - false, - ["sign"], - ); - const signature = await crypto.subtle.sign("HMAC", key, new TextEncoder().encode(message)); - return Array.from(new Uint8Array(signature), (byte) => byte.toString(16).padStart(2, "0")).join( - "", - ); -} diff --git a/.cloudflare/ci/src/index.ts b/.cloudflare/ci/src/index.ts index d6778fc..a33b08e 100644 --- a/.cloudflare/ci/src/index.ts +++ b/.cloudflare/ci/src/index.ts @@ -1,83 +1,86 @@ -import { WorkflowEntrypoint, type WorkflowEvent, type WorkflowStep } from "cloudflare:workers"; import { - DOWNLOAD_SOURCE, - commentOnPullRequest, - pullRequestHead, - serveSource, - sourceUrl, - writeCheck, -} from "./github"; + WorkflowEntrypoint, + type RunnerOutput, + type WorkflowEvent, + type WorkflowStep, +} from "cloudflare:workers"; +import { commentOnPullRequest, pullRequestHead, writeCheck } from "./github"; type Params = { sha?: string; mr?: number }; type Job = { name: string; command: string }; -type RunContext = { env: Env; step: WorkflowStep; sha: string; source: string; runUrl: string }; +type RunContext = { env: Env; step: WorkflowStep; sha: string; runUrl: string }; type RunResult = { passed: boolean; exitCode: number | null; + /** Why the job failed, when the exit code does not say it. */ + reason?: string; log?: string; truncated?: boolean; error?: string; }; -type JobResult = { check: string; passed: boolean; exitCode: number | null; checkRunId: number }; +type JobResult = { check: string; passed: boolean; reason?: string; checkRunId: number }; + +type Workspace = { inputs: RunnerOutput[]; installCached: boolean }; + +// The managed image has Node.js 24, Corepack (pnpm and yarn), git, jq, curl, and build-essential. +const IMAGE = "workflows/node"; + +// The repository is public, so a runner can fetch any commit by SHA without a +// token, also the head of a fork PR. deps/ gets only the files that the install +// reads, so the install cache stays valid while they do not change. +const CHECKOUT = [ + "git init -q repo && cd repo", + 'git fetch -q --depth 1 "$REMOTE" "$COMMIT"', + "git checkout -q FETCH_HEAD && git log --oneline -1", + "mkdir -p ../deps && cp package.json pnpm-lock.yaml pnpm-workspace.yaml ../deps/", +].join(" && "); -// The default image has Node.js 24, npm, and Corepack, but no pnpm or git. // Corepack installs the pnpm version from package.json "packageManager". // --ignore-scripts skips the root `prepare` script (`vp config`), which sets up -// Git hooks and fails without a git binary. The repo allows no dependency -// build scripts, so nothing else is skipped. -const INSTALL = [ - DOWNLOAD_SOURCE, - "cd repo", - "{ command -v corepack > /dev/null || npm install -g corepack; }", - "corepack enable", - "pnpm install --frozen-lockfile --ignore-scripts", -].join(" && "); +// Git hooks. The install step has only the manifest files, so there is nothing +// to set up. The repository allows no dependency build scripts. +const INSTALL = "cd repo && corepack enable && pnpm install --frozen-lockfile --ignore-scripts"; +// Each job runs in repo/ with node_modules restored. const JOBS: Job[] = [ { - // The "build" job in .github/workflows/test.yml. Runners get no Git - // history, so compare dist/ with a copy instead of `git diff`. + // The "build" job in .github/workflows/test.yml. name: "build", command: [ - INSTALL, "pnpm run typecheck", "pnpm run check", - "cp -R dist /tmp/dist-before", "pnpm run build", - `{ diff -rq /tmp/dist-before dist || { echo "dist/ is out of date. Run 'vp run build' and commit."; exit 1; }; }`, + `{ git diff --exit-code dist/ || { echo "dist/ is out of date. Run 'vp run build' and commit."; exit 1; }; }`, ].join(" && "), }, { // The "Unit tests (ubuntu-latest)" job. Some tests read dist/, so build first. - // src/gitlab/workflow.test.ts runs the gitlab-e2e.yml script, which needs jq. - // GitHub-hosted runners include jq, but the default image does not. name: "unit-tests", - command: [ - "apt-get update -qq", - "apt-get install -y -qq jq > /dev/null", - INSTALL, - "pnpm run build", - "pnpm run test", - ].join(" && "), + command: ["pnpm run build", "pnpm run test"].join(" && "), }, ]; -// Checks run once. A step timeout fails the step even with allowFailure, and -// the step loses its logs. -const RUNNER_CONFIG = { retries: { limit: 0, delay: "1 second" }, timeout: "15 minutes" } as const; +// Checkout and install can fail on the network, so retry them. +const SETUP_CONFIG = { + retries: { limit: 2, delay: "10 seconds", backoff: "exponential" }, + timeout: "10 minutes", +} as const; + +// Jobs run once. A step timeout fails the step even with allowFailure, and the +// step loses its logs. +const JOB_CONFIG = { retries: { limit: 0, delay: "1 second" }, timeout: "15 minutes" } as const; -// Stop each command before the step timeout, so that its logs are kept. +// Stop each job before the step timeout, so that its logs are kept. // `timeout` exits with 124 when it stops the command. const COMMAND_TIMEOUT_MINUTES = 14; const TIMEOUT_EXIT_CODE = 124; const RUNNER_ENV = { CI: "true", - DEBIAN_FRONTEND: "noninteractive", COREPACK_ENABLE_DOWNLOAD_PROMPT: "0", NPM_CONFIG_UPDATE_NOTIFIER: "false", // Keep ANSI color codes out of the log in the check summary. @@ -86,7 +89,7 @@ const RUNNER_ENV = { }; // Bumped on each change, because `instances list` does not show which code ran. -const PIPELINE_VERSION = "2026-11-17.6"; +const PIPELINE_VERSION = "2026-11-20.1"; export class CI extends WorkflowEntrypoint { async run(event: WorkflowEvent, step: WorkflowStep) { @@ -101,59 +104,98 @@ export class CI extends WorkflowEntrypoint { return pullRequestHead(env, mr); }); - const source = await step.do("sign source URL", { sensitive: "output" }, () => - sourceUrl(env, sha), - ); + const context: RunContext = { env, step, sha, runUrl }; + await Promise.all(JOBS.map(({ name }) => startCheck(context, name))); - const context: RunContext = { env, step, sha, source, runUrl }; - const results = await Promise.all(JOBS.map((job) => runJob(context, job))); + const { results, installCached } = await runJobs(context); + const passed = results.every((result) => result.passed); - if (mr) { + // Comment only when a check fails. Cloudflare CI cannot update a comment + // yet, so each comment is a new one. + if (mr && !passed) { await step.do("comment on pull request", () => commentOnPullRequest(env, mr, formatComment(context, mr, results)), ); } - const passed = results.every((result) => result.passed); - return { conclusion: passed ? "passed" : "failed", sha, version: PIPELINE_VERSION, results }; + return { + conclusion: passed ? "passed" : "failed", + sha, + version: PIPELINE_VERSION, + installCached, + results, + }; } } -// Runs one job in a runner and reports it as a GitHub check. -async function runJob(context: RunContext, { name, command }: Job): Promise { - const { env, step, sha, runUrl } = context; - const check = `cloudflare-ci/${name}`; - await step.do(`start ${name}`, () => - writeCheck(env, sha, check, { status: "in_progress", detailsUrl: runUrl }), +// Checks out the commit, installs the dependencies, and runs the jobs in +// parallel. If the checkout or the install fails, every check fails. +async function runJobs(context: RunContext) { + let workspace: Workspace; + try { + workspace = await prepareWorkspace(context); + } catch (error) { + const failure: RunResult = { + passed: false, + exitCode: null, + reason: "checkout or install failed", + error: errorMessage(error), + }; + const results = await Promise.all( + JOBS.map(({ name }) => completeCheck(context, name, failure)), + ); + return { results, installCached: false }; + } + + const results = await Promise.all( + JOBS.map(async (job) => + completeCheck(context, job.name, await runJob(context.step, job, workspace.inputs)), + ), ); + return { results, installCached: workspace.installCached }; +} - const result = await runCommand(step, name, command, context.source); +async function prepareWorkspace({ env, step, sha }: RunContext): Promise { + const checkout = await step.runner("checkout", SETUP_CONFIG, { + image: IMAGE, + command: CHECKOUT, + env: { ...RUNNER_ENV, REMOTE: `https://github.com/${env.GITHUB_REPO}.git`, COMMIT: sha }, + outputs: { repo: "repo", deps: "deps" }, + }); + const { repo, deps } = checkout.outputs; + if (!repo || !deps) throw new Error("The checkout saved no files."); - const { checkRunId } = await step.do(`complete ${name}`, () => - writeCheck(env, sha, check, { - status: "completed", - conclusion: result.passed ? "success" : "failure", - title: result.passed ? "Passed" : `Failed (${failureReason(result.exitCode)})`, - summary: formatSummary(result), - detailsUrl: runUrl, - }), - ); - return { check, passed: result.passed, exitCode: result.exitCode, checkRunId }; + // Restore the manifest files in repo/, so that node_modules has the same path + // here and in the jobs. cache: true skips the install, and starts no + // container, while the manifest files do not change. + const install = await step.runner("install", SETUP_CONFIG, { + image: IMAGE, + command: INSTALL, + env: RUNNER_ENV, + inputs: [{ ...deps, path: "repo" }], + outputs: { modules: "repo/node_modules" }, + cache: true, + }); + const { modules } = install.outputs; + if (!modules) throw new Error("The install saved no node_modules."); + + return { inputs: [repo, modules], installCached: install.cached === true }; } // Step timeouts and container errors throw, even with allowFailure. Catch them, -// so that the caller can fail the check and it does not stay in progress. -async function runCommand( +// so that the check fails and does not stay in progress. +async function runJob( step: WorkflowStep, - name: string, - command: string, - source: string, + { name, command }: Job, + inputs: RunnerOutput[], ): Promise { try { - const run = await step.runner(name, RUNNER_CONFIG, { + const run = await step.runner(name, JOB_CONFIG, { + image: IMAGE, // JOB_COMMAND keeps the quotes in the job command intact inside `sh -c`. command: `timeout ${COMMAND_TIMEOUT_MINUTES}m sh -c "$JOB_COMMAND"`, - env: { ...RUNNER_ENV, SOURCE_URL: source, JOB_COMMAND: command }, + env: { ...RUNNER_ENV, JOB_COMMAND: `cd repo && corepack enable && ${command}` }, + inputs, instanceSize: "standard-3", allowFailure: true, }); @@ -165,17 +207,49 @@ async function runCommand( truncated: run.logs.truncated, }; } catch (error) { - const message = error instanceof Error ? `${error.name}: ${error.message}` : String(error); - return { passed: false, exitCode: null, error: message }; + return { passed: false, exitCode: null, reason: "runner error", error: errorMessage(error) }; } } -function failureReason(exitCode: number | null) { - if (exitCode === null) return "runner error"; +function checkName(name: string) { + return `cloudflare-ci/${name}`; +} + +function startCheck({ env, step, sha, runUrl }: RunContext, name: string) { + return step.do(`start ${name}`, () => + writeCheck(env, sha, checkName(name), { status: "in_progress", detailsUrl: runUrl }), + ); +} + +async function completeCheck( + { env, step, sha, runUrl }: RunContext, + name: string, + result: RunResult, +): Promise { + const check = checkName(name); + const reason = result.passed ? undefined : failureReason(result); + const { checkRunId } = await step.do(`complete ${name}`, () => + writeCheck(env, sha, check, { + status: "completed", + conclusion: result.passed ? "success" : "failure", + title: reason === undefined ? "Passed" : `Failed (${reason})`, + summary: formatSummary(result), + detailsUrl: runUrl, + }), + ); + return { check, passed: result.passed, reason, checkRunId }; +} + +function failureReason({ exitCode, reason }: RunResult) { + if (reason !== undefined) return reason; if (exitCode === TIMEOUT_EXIT_CODE) return `timed out after ${COMMAND_TIMEOUT_MINUTES} minutes`; return `exit ${exitCode}`; } +function errorMessage(error: unknown) { + return error instanceof Error ? `${error.name}: ${error.message}` : String(error); +} + // The runner keeps at most 16 KiB of log, which fits in a check summary // (65,535 characters). The four-backtick fence allows ``` in the log. function formatSummary({ log, truncated, error }: RunResult) { @@ -188,9 +262,9 @@ function formatSummary({ log, truncated, error }: RunResult) { function formatComment({ env, sha, runUrl }: RunContext, mr: number, results: JobResult[]) { const checksUrl = `https://github.com/${env.GITHUB_REPO}/pull/${mr}/checks`; const lines = results.map( - ({ check, passed, exitCode, checkRunId }) => + ({ check, passed, reason, checkRunId }) => `- ${passed ? "✅" : "❌"} [\`${check}\`](${checksUrl}?check_run_id=${checkRunId})` + - (passed ? "" : ` (${failureReason(exitCode)})`), + (reason === undefined ? "" : ` (${reason})`), ); return [ `Cloudflare CI on \`${sha.slice(0, 7)}\`:`, @@ -200,4 +274,7 @@ function formatComment({ env, sha, runUrl }: RunContext, mr: number, results: Jo ].join("\n"); } -export default { fetch: serveSource } satisfies ExportedHandler; +// The Worker serves no HTTP requests. The checkout no longer needs a source server. +export default { + fetch: () => new Response("Not found", { status: 404 }), +} satisfies ExportedHandler; diff --git a/.cloudflare/ci/src/runner.d.ts b/.cloudflare/ci/src/runner.d.ts index 57cabf4..84a4687 100644 --- a/.cloudflare/ci/src/runner.d.ts +++ b/.cloudflare/ci/src/runner.d.ts @@ -9,23 +9,49 @@ declare module "cloudflare:workers" { runner(name: string, config: WorkflowStepConfig, options: RunnerOptions): Promise; } - /** A saved output of an earlier runner in the same run. */ - type RunnerOutput = object; + /** + * A saved output of a runner. Pass it to `inputs` of a later runner. Change + * `path` to restore the files somewhere else. Treat the other fields as opaque. + */ + export interface RunnerOutput { + /** Where the files are restored, relative to /workspace. */ + path: string; + /** The SHA-256 of the content. The cache key includes it. */ + hash: string; + } - interface RunnerOptions { + export interface RunnerOptions { /** A shell script, run with /bin/sh in /workspace as root. */ command: string; + /** A managed image name or an image in the account's registry. */ + image?: + | "cloudflare/debian-trixie" + | "workflows/node" + | "workflows/python" + | { repository: string; digest: string }; + /** Restored in order. A later input at the same or a parent path replaces earlier ones. */ inputs?: RunnerOutput[]; + /** Output name to a path to save after the command. */ outputs?: Record; + /** Not for secrets: values can appear in logs and step output. */ env?: Record; - image?: { repository: string; digest: string }; instanceSize?: "lite" | "basic" | "standard-1" | "standard-2" | "standard-3" | "standard-4"; allowFailure?: boolean; + /** + * Reuse the result of an earlier run with the same image, command, env, + * outputs, allowFailure, and input hashes and paths. Results are kept for + * 7 days. Allowed failures are cached too. + */ + cache?: boolean | { key?: string }; } - interface RunnerResult { + export interface RunnerResult { exitCode: number; + /** The last 16 KiB of stdout and stderr, combined in order. */ logs: { data: string; truncated: boolean }; + /** `null` when the path did not exist after an allowed failure. */ outputs: Record; + /** Set when the result came from the cache and no container ran. */ + cached?: true; } } diff --git a/.cloudflare/ci/src/scm.d.ts b/.cloudflare/ci/src/scm.d.ts index c1757fc..5129dd4 100644 --- a/.cloudflare/ci/src/scm.d.ts +++ b/.cloudflare/ci/src/scm.d.ts @@ -1,6 +1,6 @@ // Copied from the Cloudflare CI "Get started" guide. // Wrangler does not generate types for the scm binding yet. -// Changes from the docs: RUN_URL_BASE in Env. +// Changes from the docs: Env has RUN_URL_BASE and no source server variables. interface ScmRepository { checkout(target: { sha: string }): Promise; checkout(target: { mr: number }): Promise; @@ -32,7 +32,5 @@ interface Env { REPO: ScmRepository; CI_WORKFLOW: Workflow; GITHUB_REPO: string; - SOURCE_ORIGIN: string; - SOURCE_SECRET: string; RUN_URL_BASE: string; } diff --git a/.cloudflare/ci/wrangler.jsonc b/.cloudflare/ci/wrangler.jsonc index cd73735..3c53d7a 100644 --- a/.cloudflare/ci/wrangler.jsonc +++ b/.cloudflare/ci/wrangler.jsonc @@ -3,11 +3,11 @@ "name": "setup-vp-ci", "main": "src/index.ts", "compatibility_date": "2026-11-01", + // The Worker serves no HTTP requests, so it needs no workers.dev URL. + "workers_dev": false, "workflows": [{ "name": "setup-vp-ci", "binding": "CI_WORKFLOW", "class_name": "CI" }], "vars": { "GITHUB_REPO": "voidzero-dev/setup-vp", - // The Worker's workers.dev URL. Runners download the source from it. - "SOURCE_ORIGIN": "https://setup-vp-ci.voidzero-docs.workers.dev", // The dashboard URL of a run, without the instance ID. Checks link to it. "RUN_URL_BASE": "https://dash.cloudflare.com/f8b59a295069bd81a0f256b7012f2c53/workers/workflows/setup-vp-ci/instance/", }, @@ -23,6 +23,7 @@ "checks:write", "comments:write", "merge_requests:read", + // pullRequestHead() reads the PR head SHA through outbound(). "outbound:read", ], }, diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a7ffdba..3dc21b4 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -128,7 +128,7 @@ GitHub triggers are not available yet, so start each run with Wrangler: ```bash cd .cloudflare/ci -# A pull request: posts the checks and a new PR comment. +# A pull request: posts the checks, and a PR comment if a check fails. npx wrangler@4.163.0 workflows trigger setup-vp-ci '{"mr":123}' # A commit (full SHA): posts or updates the checks, with no comment. @@ -139,7 +139,7 @@ npx wrangler@4.163.0 workflows instances list setup-vp-ci npx wrangler@4.163.0 workflows instances describe setup-vp-ci ``` -Each `mr` run posts a new PR comment. To run a PR again without another comment, start the run with the PR head SHA. +An `mr` run posts a PR comment only when a check fails. Cloudflare CI cannot update a comment yet, so each failed run posts a new one. A second run on the same commit updates the same checks. ### Read Logs @@ -173,11 +173,12 @@ Each `mr` run posts a new PR comment. To run a PR again without another comment, ### Runner Environment -- The default runner image has Node.js 24, npm, and Corepack, but no `git`, `jq`, or `pnpm`. GitHub CI uses `lts/*` from `.node-version`. -- The install uses `pnpm install --ignore-scripts`, because the root `prepare` script (`vp config`) fails without `git`. The repository allows no dependency build scripts, so the flag skips nothing else. -- The `unit-tests` runner installs `jq` with `apt-get`, because `src/gitlab/workflow.test.ts` runs the GitLab E2E workflow script, which uses `jq`. -- Runners cannot check out code from GitHub yet. The Worker serves each commit as a tarball through a signed URL, so runners have no Git history. `SOURCE_SECRET` signs the URLs. To replace it, run `openssl rand -hex 32 | npx wrangler@4.163.0 secret put SOURCE_SECRET` in `.cloudflare/ci/`. -- `@cloudflare/workers-types` does not include `step.runner()`. [`runner.d.ts`](.cloudflare/ci/src/runner.d.ts) declares the result that the runtime returns, `logs: { data, truncated }`. The Cloudflare CI docs show `logs.stdout` and `logs.stderr` instead. +- Every runner uses the managed `workflows/node` image. It has Node.js 24, Corepack (pnpm and yarn), `git`, `jq`, `curl`, and build-essential. GitHub CI uses `lts/*` from `.node-version`. +- The `checkout` step fetches the commit from GitHub with `git fetch --depth 1`. The repository is public, so this needs no token, also for the head of a fork PR. The `build` job compares `dist/` with `git diff --exit-code`, the same as `test.yml`. +- The `install` step gets only `package.json`, `pnpm-lock.yaml`, and `pnpm-workspace.yaml`, and saves `node_modules` for the jobs. It uses the runner cache, so a run skips it while those files do not change. The cache keeps results for 7 days. `output.installCached` in the run result shows whether the install came from the cache. +- The install uses `pnpm install --ignore-scripts`. The root `prepare` script (`vp config`) sets up Git hooks, and the install step has no repository to set them up in. The repository allows no dependency build scripts, so the flag skips nothing else. +- If the checkout or the install fails, both checks fail with the error. These steps retry 2 times, because network errors can cause them. +- `@cloudflare/workers-types` does not include `step.runner()`. [`runner.d.ts`](.cloudflare/ci/src/runner.d.ts) declares it with the result that the runtime returns, `logs: { data, truncated }`. The Cloudflare CI docs show `logs.stdout` and `logs.stderr` instead. ## Dependency Updates From aeb3f0b55728d8d396be250589ea1bfc6175b3fd Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Fri, 20 Nov 2026 12:30:58 +0800 Subject: [PATCH 5/5] test: fail on purpose to show a failed Cloudflare CI check Do not merge. Remove this commit before the PR leaves draft. Co-Authored-By: Claude Opus 5.5 --- src/cloudflare-ci-failure.test.ts | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 src/cloudflare-ci-failure.test.ts diff --git a/src/cloudflare-ci-failure.test.ts b/src/cloudflare-ci-failure.test.ts new file mode 100644 index 0000000..d85f5b5 --- /dev/null +++ b/src/cloudflare-ci-failure.test.ts @@ -0,0 +1,6 @@ +import { expect, it } from "vite-plus/test"; + +// Fails on purpose to show a failed Cloudflare CI check. Do not merge. +it("fails on purpose to show a failed Cloudflare CI check", () => { + expect({ answer: 1 + 1 }).toEqual({ answer: 3 }); +});