GeoHarness

GeoHarness documentation

GeoHarness is a composite GitHub Action: uses: Avarok-Cybersecurity/geoharness@v1. Everything it needs comes from its inputs and a geoharness.toml in your site directory; this page lists the inputs and outputs, and the pages below cover the rest.

Version 1.0 · Updated

What is in the documentation?

Inputs

GitHub does not enforce required for composite actions, so GeoHarness validates every input itself in preflight and reports all problems at once. Inputs reach the CLI as environment variables and are never interpolated into a shell.

Action inputs (from action.yml)
InputRequiredDefaultDescription
cloudflare-api-tokenno—Cloudflare API token. Permission groups per feature are listed in cloudflare-permissions.json. Required when deploy is true.
cloudflare-account-idno—Cloudflare account ID (32 hex characters). Required when deploy is true.
site-pathyes—Directory of the site inside the repository; it must contain geoharness.toml.
adapternoautoBuild adapter: auto (detect), static, command, npm, sveltekit-static, python, make, vite-prerender, worker-assets.
build-commandno—Build command, run without a shell (quotes group words; pipes, redirects, ; & $ are rejected — use a script).
output-dirno—Build output directory relative to site-path. Required by static, command, python and make.
targetnoworkersDeploy target: workers (assets-only Worker on Custom Domains) or pages.
project-nameyes—Worker or Pages project name (lower-case letters, digits, hyphens).
domainsyes—Newline-separated host names to serve the site on. The host of site.origin in geoharness.toml must be one of them.
lighthousenotrueRun the Lighthouse gate (100 in all four categories, median of 3 runs). false skips it.
lighthouse-max-urlsno—How many URLs from the generated sitemap Lighthouse audits. Required when lighthouse is true.
geo-min-scoreyes—Minimum GEO score (0–100) for the build audit and the live audit.
extra-optimizationsnoallFree zone optimizations, as tokens applied left to right: all, none, <id>, -<id>. Ids: email_obfuscation, rocket_loader, early_hints, http3, brotli, smart_tiered_cache, zstd, bot_fight_mode, ai_bots_protection. Example: "all -rocket_loader".
deploynotruetrue deploys, configures the zone, verifies live and pings IndexNow. false is a dry run for pull requests: build, process, GEO audit and Lighthouse only, with no Cloudflare API call.
ragnofalseComing in v1.1 (RAG index export). Not implemented yet; setting it to true fails the run.

Outputs

Action outputs
OutputDescription
geo-scoreGEO score of the live site (the build audit's when the run stopped before verify).
urlThe deployed URL.
markdown-countNumber of markdown twins generated.

How do I run it on pull requests without deploying?

Set deploy: false. The run builds, processes, audits and runs Lighthouse, then stops: no Cloudflare API call, no deploy, no zone change, and no credentials are needed, so it is safe for pull requests from forks. The job summary says it was a dry run.

Can I run it outside GitHub Actions?

Yes. node dist/cli.mjs run runs every stage with the same INPUT_* environment variables the action sets; node dist/cli.mjs <stage> runs one stage, carrying state in GEOHARNESS_STATE_DIR. node dist/cli.mjs audit https://example.com/ audits any live URL without a configuration file, judging only what the site serves.