Deploy from CI

Build your website in CI and send the output to fortropp on every push. This page sets it up with GitHub Actions; the same script runs anywhere Node 22 does.

1. Create a token

On the API & Agents page, create a token with access to just this website. In your GitHub repository, add it as the secret FORTROPP_TOKEN.

2. Add your website ID

Copy the website ID from the Routing config card on the website's Delivery page, and add it as the repository variable FORTROPP_WEBSITE_ID.

3. Add the script

Save this as .github/fortropp-deploy.mjs:

import { createHash } from 'node:crypto';
import { readdir, readFile } from 'node:fs/promises';
import { join, relative, sep } from 'node:path';
import { parseArgs } from 'node:util';

const UPLOAD_CONCURRENCY = 8;

function required(name) {
	const value = process.env[name];
	if (!value) throw new Error(`Set ${name}`);
	return value;
}

const api = required('FORTROPP_API');
const token = required('FORTROPP_TOKEN');
const websiteId = required('FORTROPP_WEBSITE_ID');
const { values, positionals } = parseArgs({
	allowPositionals: true,
	options: {
		'read-revision': { type: 'boolean' },
		publish: { type: 'boolean' },
		live: { type: 'boolean', default: false },
		force: { type: 'boolean', default: false },
		name: { type: 'string' }
	}
});
const dir = positionals[0] ?? '.';

async function call(method, path, body) {
	const res = await fetch(`${api}/files/${websiteId}${path}`, {
		method,
		headers: { authorization: `Bearer ${token}`, 'content-type': 'application/json' },
		body: JSON.stringify(body)
	});
	if (!res.ok) throw new Error(`${method} ${path}: ${res.status} ${await res.text()}`);
	return res.json();
}

if (values['read-revision']) {
	const { revision } = await call('GET', '/state');
	console.log(`FORTROPP_REVISION=${revision}`);
	process.exit(0);
}

const expectedRevision = values.publish ? Number(required('FORTROPP_REVISION')) : null;

const files = [];
for (const entry of await readdir(dir, { withFileTypes: true, recursive: true })) {
	if (!entry.isFile()) continue;
	const absolute = join(entry.parentPath, entry.name);
	const bytes = await readFile(absolute);
	files.push({
		absolute,
		path: relative(dir, absolute).split(sep).join('/'),
		hash: createHash('sha256').update(bytes).digest('hex'),
		size: bytes.length
	});
}

const byHash = new Map(files.map((file) => [file.hash, file]));
const { uploads } = await call('POST', '/site_files/upload_plan', {
	blobs: [...byHash.values()].map(({ hash, size }) => ({ hash, size_bytes: size }))
});

const queue = [...uploads];
await Promise.all(
	Array.from({ length: UPLOAD_CONCURRENCY }, async () => {
		for (let next = queue.shift(); next; next = queue.shift()) {
			const body = await readFile(byHash.get(next.hash).absolute);
			const res = await fetch(next.url, { method: 'PUT', headers: next.headers, body });
			if (!res.ok) throw new Error(`Upload of ${byHash.get(next.hash).path}: ${res.status}`);
		}
	})
);

const { snapshot } = await call('PUT', `/site_files${values.force ? '?force=true' : ''}`, {
	files: files.map(({ path, hash }) => ({ path, hash }))
});
const uploadedHashes = new Set(uploads.map(({ hash }) => hash));
const uploaded = files.filter(({ hash }) => uploadedHashes.has(hash)).length;
console.log(
	`Saw ${files.length} files; ${uploaded} were uploaded, ${files.length - uploaded} were already stored.`
);

if (values.publish) {
	await call('POST', '/deploys', {
		name: values.name,
		expected_revision: expectedRevision,
		expected_files: snapshot,
		make_live: values.live
	});
	console.log(values.live ? 'Published and made live' : 'Published');
}

4. Add the workflow

Save this as .github/workflows/deploy.yml, changing the build command and dist to match your project:

name: Deploy
on:
  push:
    branches: [main]
jobs:
  deploy:
    runs-on: ubuntu-latest
    env:
      FORTROPP_API: http://sveltekit-prerender/api
      FORTROPP_WEBSITE_ID: ${{ vars.FORTROPP_WEBSITE_ID }}
      FORTROPP_TOKEN: ${{ secrets.FORTROPP_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: node .github/fortropp-deploy.mjs --read-revision >> "$GITHUB_ENV"
      - run: npm ci && npm run build
      - run: node .github/fortropp-deploy.mjs dist --publish --live --name "Commit ${GITHUB_SHA::7}"

What the script does

It makes your website's files exactly the contents of the folder: new and changed files are added, and files that are no longer in the folder are removed. Files fortropp already has aren't uploaded again.

With --publish, it then saves the draft as a new version, named with --name. Add --live to also make that version what visitors see. Leave --publish out to update the draft only and publish from the dashboard after checking the preview. Either way, the version shows the token's name as who published it.

If the website has unpublished changes that differ from the folder, the script stops with an error rather than overwrite them. Publish or discard them, or add --force to overwrite them.

The workflow's first step reads the website's current revision, before your build starts. Publishing is refused if anything has changed since then, such as someone making another version live while the build ran, and the job fails with an error. Run the job again to publish.

The API

The script uses these calls, which also accept Authorization: Bearer <token> from your own tooling. Paths are under http://sveltekit-prerender/api/files/<website ID>.

  • POST /site_files/upload_plan with { blobs: [{ hash, size_bytes }] } returns { uploads: [{ hash, url, headers }] } for each file fortropp doesn't have yet. Send the bytes with a PUT to url, with exactly those headers. The upload is refused unless the bytes match the hash and size you planned.
  • PUT /site_files with { files: [{ path, hash, content_type? }] } makes the website's files exactly these files, and returns them with their snapshot. Refused with 409 if that would overwrite unpublished changes, unless you add ?force=true.
  • POST /site_files with { put: [...], delete: [path] } adds, replaces and removes only the files listed.
  • GET /site_files lists the website's files.
  • GET /state returns the website's revision, files, its head and live versions, and its draft with changes, or null if there is no draft.
  • POST /deploys with { name?, expected_revision, expected_files, make_live } saves the draft as a version. Read revision and files from GET /state. If either no longer matches, the call fails with 409 and nothing is published.

Hashes are lowercase hex SHA-256 of the file's bytes.