---
title: "Documentation · GeoHarness"
description: "How to use the GeoHarness GitHub Action: every input and output, dry runs for pull requests, and links to configuration, adapters, Cloudflare setup, GEO score and security."
canonical: "https://geo.avarok.net/docs/"
tokens: 2771
---

# 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 2026-11-19

## What is in the documentation?

- [geoharness.toml reference](https://geo.avarok.net/docs/config/): every key, its validation and the few defaults (each with a reason).
- [Adapters and runtime detection](https://geo.avarok.net/docs/adapters/): how GeoHarness finds and runs your build.
- [Cloudflare setup](https://geo.avarok.net/docs/cloudflare/): the API token, the permission groups per feature, free-tier limits and fail modes.
- [GEO score and Lighthouse](https://geo.avarok.net/docs/geo-score/): every check, its evidence grade and its citations, and the Lighthouse policy.
- [Security model](https://geo.avarok.net/docs/security/): 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.

Action inputs (from action.yml)

| 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 gates (100 in all four categories, median of 3 runs): before deploy against the output served locally by wrangler with the deploy's own config, and after deploy against the live site. false skips both.                                                                                                                                                                    |
| `lighthouse-max-urls`   | no       | —         | How many URLs from the generated sitemap Lighthouse audits, locally and live. 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.                                                                                                                                                                                                          |
| `rollback-on-failure`   | no       | —         | Required when deploy is true (no default). true: when the post-deploy verification (live GEO audit or the production Lighthouse gate) fails, put production back on the version it served before this deploy (wrangler rollback for workers, the Pages rollback API for pages), then fail. false: fail and leave the new build live. A first deploy has nothing to roll back to and just fails. |
| `rag`                   | no       | `false`   | Coming in v1.1 (RAG index export). Not implemented yet; setting it to true fails the run.                                                                                                                                                                                                                                                                                                       |

## Outputs

Action 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.

```json
{
  "@context": "https://schema.org",
  "@type": "WebPage",
  "author": {
    "@type": "Organization",
    "name": "Avarok Cybersecurity",
    "sameAs": [
      "https://github.com/Avarok-Cybersecurity"
    ],
    "url": "https://avarok.net"
  },
  "description": "How to use the GeoHarness GitHub Action: every input and output, dry runs for pull requests, and links to configuration, adapters, Cloudflare setup, GEO score and security.",
  "inLanguage": "en",
  "isPartOf": {
    "@type": "WebSite",
    "name": "GeoHarness",
    "url": "https://geo.avarok.net/"
  },
  "name": "Documentation · GeoHarness",
  "url": "https://geo.avarok.net/docs/"
}
```
