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_planwith{ blobs: [{ hash, size_bytes }] }returns{ uploads: [{ hash, url, headers }] }for each filefortroppdoesn't have yet. Send the bytes with aPUTtourl, with exactly thoseheaders. The upload is refused unless the bytes match the hash and size you planned.PUT /site_fileswith{ files: [{ path, hash, content_type? }] }makes the website's files exactly these files, and returns them with theirsnapshot. Refused with409if that would overwrite unpublished changes, unless you add?force=true.POST /site_fileswith{ put: [...], delete: [path] }adds, replaces and removes only the files listed.GET /site_fileslists the website's files.GET /statereturns the website'srevision,files, itsheadandliveversions, and itsdraftwithchanges, or null if there is no draft.POST /deployswith{ name?, expected_revision, expected_files, make_live }saves the draft as a version. ReadrevisionandfilesfromGET /state. If either no longer matches, the call fails with409and nothing is published.
Hashes are lowercase hex SHA-256 of the file's bytes.