Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 94 additions & 0 deletions .cloudflare/ci/src/github.ts
Original file line number Diff line number Diff line change
@@ -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(
"",
);
}
203 changes: 203 additions & 0 deletions .cloudflare/ci/src/index.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,203 @@
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 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; 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".
// --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 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.6";

export class CI extends WorkflowEntrypoint<Env, Params> {
async run(event: WorkflowEvent<Params>, 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;
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 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(context, mr, 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(context: RunContext, { name, command }: Job): Promise<JobResult> {
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 }),
);

const result = await runCommand(step, name, command, context.source);

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 };
}

// 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,
command: string,
source: string,
): Promise<RunResult> {
try {
const run = await step.runner(name, RUNNER_CONFIG, {
// 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,
});
// The runner returns one combined log stream: { data, truncated }.
return {
passed: run.exitCode === 0,
exitCode: run.exitCode,
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, error: message };
}
}

function failureReason(exitCode: number | null) {
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\`\`\`\``;
}

// Each check name links to its check page on the PR, which shows the runner log.
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 }) =>
`- ${passed ? "✅" : "❌"} [\`${check}\`](${checksUrl}?check_run_id=${checkRunId})` +
(passed ? "" : ` (${failureReason(exitCode)})`),
);
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<Env>;
31 changes: 31 additions & 0 deletions .cloudflare/ci/src/runner.d.ts
Original file line number Diff line number Diff line change
@@ -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<RunnerResult>;
runner(name: string, config: WorkflowStepConfig, options: RunnerOptions): Promise<RunnerResult>;
}

/** 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<string, string>;
env?: Record<string, string>;
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<string, RunnerOutput | null>;
}
}
38 changes: 38 additions & 0 deletions .cloudflare/ci/src/scm.d.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,38 @@
// 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<ScmCheckout & Disposable>;
checkout(target: { mr: number }): Promise<ScmMergeRequestCheckout & Disposable>;
outbound(): Promise<Fetcher>;
}

interface ScmCheckout {
readonly checks: {
write(name: string, update: ScmCheckUpdate): Promise<{ checkRunId: number; url: string }>;
};
readFile(file: { path: string }): Promise<string>;
}

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;
RUN_URL_BASE: string;
}
17 changes: 17 additions & 0 deletions .cloudflare/ci/tsconfig.json
Original file line number Diff line number Diff line change
@@ -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/**/*"]
}
Loading
Loading