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.
What is in the documentation?
- geoharness.toml reference: every key, its validation and the few defaults (each with a reason).
- Adapters and runtime detection: how GeoHarness finds and runs your build.
- Cloudflare setup: the API token, the permission groups per feature, free-tier limits and fail modes.
- GEO score and Lighthouse: every check, its evidence grade and its citations, and the Lighthouse policy.
- Security model: what GeoHarness can touch and how it is contained.
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.
| Input | Required | Default | Description |
|---|---|---|---|
cloudflare-api-token | no | — | Cloudflare API token. Permission groups per feature are listed in cloudflare-permissions.json. Required when deploy is true. |
cloudflare-account-id | no | — | Cloudflare account ID (32 hex characters). Required when deploy is true. |
site-path | yes | — | Directory of the site inside the repository; it must contain geoharness.toml. |
adapter | no | auto | Build adapter: auto (detect), static, command, npm, sveltekit-static, python, make, vite-prerender, worker-assets. |
build-command | no | — | Build command, run without a shell (quotes group words; pipes, redirects, ; & $ are rejected — use a script). |
output-dir | no | — | Build output directory relative to site-path. Required by static, command, python and make. |
target | no | workers | Deploy target: workers (assets-only Worker on Custom Domains) or pages. |
project-name | yes | — | Worker or Pages project name (lower-case letters, digits, hyphens). |
domains | yes | — | Newline-separated host names to serve the site on. The host of site.origin in geoharness.toml must be one of them. |
lighthouse | no | true | Run the Lighthouse gate (100 in all four categories, median of 3 runs). false skips it. |
lighthouse-max-urls | no | — | How many URLs from the generated sitemap Lighthouse audits. Required when lighthouse is true. |
geo-min-score | yes | — | Minimum GEO score (0–100) for the build audit and the live audit. |
extra-optimizations | no | all | Free 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". |
deploy | no | true | true 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. |
rag | no | false | Coming in v1.1 (RAG index export). Not implemented yet; setting it to true fails the run. |
Outputs
| Output | Description |
|---|---|
geo-score | GEO score of the live site (the build audit's when the run stopped before verify). |
url | The deployed URL. |
markdown-count | Number 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.