From ef17292b4a4587cb5282e40d2ee96fff2001c2d4 Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 14:46:19 +0800 Subject: [PATCH 1/4] 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/4] 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 a5d2b4417d4fc8df1c106dab2f4ba907d8765aad Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 15:01:45 +0800 Subject: [PATCH 3/4] 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 }); +}); From 18b879ff3ae50e0dfb931390d4e769d5eb10a8b9 Mon Sep 17 00:00:00 2001 From: "MK (fengmk2)" Date: Tue, 17 Nov 2026 15:11:45 +0800 Subject: [PATCH 4/4] 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: