The choices the walkthrough did not make

The walkthrough above takes the shortest working path. These are the branches it passed by. None of them is tested, because each one needs an external system that a test cannot honestly stand in for — but each one is a decision a real installation makes, so here is what it involves.

Authentication

Local accounts — Gheetah stores the accounts itself. Nothing else is needed, and users are created from Admin → Users. This is the right choice for an evaluation, a single team, or an installation with no directory to integrate with.

Microsoft Azure AD / Entra ID — register Gheetah as an application in your tenant, then give the wizard the tenant id, client id and client secret. People sign in with their work accounts and Gheetah never sees a password. Group membership can be mapped onto Gheetah's permission groups, so joining a directory group is what grants access.

Google — the same arrangement with a Google Cloud OAuth client: client id and client secret, and a redirect URI that points back at your Gheetah address.

Generic SSO — for any other OpenID Connect provider: the authority URL, client id, client secret and the scopes to request.

Whichever is chosen, it can be changed afterwards in Settings → Authentication. Changing it does not delete the accounts that already exist.

Data storage

Every option supports every feature. What differs is operation.

Local JSON — Gheetah writes its own files under Data/. No database to run, no connection string, and the whole installation can be backed up by copying a folder. Best for evaluation and single-machine installations.

SQLite — one embedded database file. Still nothing to run, but with real transactions and indexes; a good step up when the JSON files grow large.

PostgreSQL — a shared server, documents stored in JSONB columns with indexes on the fields Gheetah filters and orders by. This is the usual choice for a team installation: the database is backed up, replicated and monitored the way the rest of your estate is.

MongoDB — a document database, if that is what your organisation already runs.

Cosmos DB — Azure's managed document database, for installations that must stay inside Azure.

The wizard asks for a connection string and tests the connection before it lets you continue, so a wrong string is caught here rather than after the installation.

Project folder

The project folder can be left empty during the installation and set later in Settings. Gheetah needs it before the first project is added: it is where repositories are cloned, archives are unpacked and generated projects are written. Point it at a disk with room for as many working copies as your team will hold.

The other two ways a project arrives

Generating is one of three. The other two bring a project that already exists, and both end in the same place: a project in the list, waiting to be built.

Clone from a repository

Settings → Git Repos is where a connection to GitHub, GitLab, Bitbucket or Azure DevOps is configured once, with a token that Gheetah stores encrypted. The Clone tab then offers the repositories that connection can see, so nobody pastes a URL or a token into the project form.

Pick the repository and the language it is written in. Gheetah clones it into the project folder, and from then on the project is Gheetah's working copy: the editor commits to it, the pull-request view reads it, and a build runs against it.

Upload an archive

For a project that is not in a repository Gheetah can reach — a proof of concept on someone's laptop, or a repository behind a network Gheetah is not on. Zip the project folder and upload it. Gheetah unpacks it into the project folder and treats it exactly like a cloned one, except that there is nowhere to push back to.

What all three have in common

Whichever way it arrived, the project has to be built before its scenarios can run, and the build happens on the server rather than on the machine of whoever added it. A project that does not compile is listed as failed with the compiler's own output, which is the fastest way to find a missing package or a wrong target framework.

Languages and targets

C# and Java each offer Web, Desktop and Mobile; Playwright offers Web. A generated project is complete for its combination: the runner for the chosen test framework, the driver setup, a step library, a showcase feature and a smoke scenario that passes offline — so the first run is green before a single line is written.

The two add-ons are step libraries rather than project types. API Steps adds HTTP steps (RestSharp for C#, REST Assured for Java) and Database Steps adds SQL ones (Dapper, or Hibernate with the JDBC driver). Both can be added by hand later; ticking them here only saves writing the packages and the step definitions yourself.

What the runtime images need, and the other kind of target

Runtime images are built on the server

Gheetah does not ship prebuilt runner images. Each runtime — Playwright, C#, Java, Maestro — is built on the Docker server itself from a Dockerfile Gheetah copies there. That is what lets a team pin the versions they need and audit what runs their tests, and it is why provisioning is the long step: the first build of the C# runtime pulls the .NET SDK image and installs a browser into it.

It asks two things of the server: enough disk for the images, and a Docker daemon that can reach a registry. A server behind a proxy needs Docker configured for that proxy before this step, not after. Readiness is remembered per runtime, so a server can be registered with C# ready and Java failed, and used for C# projects while Java is sorted out.

One arrangement fails for a reason worth knowing. A Docker host that is itself a container running its own daemon — Docker inside Docker, the usual shortcut for a demonstration — cannot extract the layers of the base images:

failed to convert whiteout file ".wh.PowerShell.Linux.x64.7.4.20.nupkg": operation not permitted

That is overlayfs refusing to create whiteout files on top of overlayfs, and it happens to a plain docker pull with no Gheetah involved. It is not a limit of the product or of the image: on an ordinary Ubuntu or Debian server — which is what Gheetah supports and what a team registers — the same provisioning builds and reports Ready. If you are evaluating Gheetah with a nested host and see a runtime fail here, give it a real host or a daemon of its own, and it will build.

The other kind of target: an agent

A Docker server is not the only place tests run. The GheetahAgent is a desktop application installed on a machine of your own — a tester's laptop with a particular browser and version, a Windows machine for a desktop application under test, a machine with phones attached. The agent connects back to Gheetah and waits; an administrator approves it once, and from then on it appears in the same target list the Docker servers do.

Use a Docker server when the test only needs a browser and you want runs to be identical and disposable. Use an agent when the test needs something a container cannot have: a specific operating system, a real GPU, a device plugged into a USB port, or software that is only licensed on one machine.

Execution policy

A run can be told where to go, or left to Gheetah. The policies are Docker-only, Docker-preferred, agent-only and local, and the choice is recorded with the run — so a result can always be traced back to where it ran and why that target was picked.

What else a run can be told, and where it can go wrong

One scenario means one scenario

Selecting a scenario and pressing Run Scenario runs that scenario and nothing else. It is worth saying because it was not always so: the run used to be filtered by the scenario's first tag, and since a generated project tags its whole feature @Web, asking for one scenario ran every scenario in the project that carried it. The report that came back was then somebody else's.

A run is now filtered by the scenario's title — dotnet test matches it on the display name and the fully qualified name, Cucumber on --name, Playwright on --grep. Tags still filter when a tag is what you asked for, which is what the tag filter in Run Options is.

Running more than one

Run All Scenarios runs the project. With a tag chosen in Run Options it runs the scenarios carrying that tag — which is how a team runs a smoke set, a regression set, or everything tagged for a release.

Tags come from the feature files, so the list Gheetah offers is the list your scenarios actually use.

Where a run can go wrong before it starts

• No execution target. Nothing is registered, or nothing with the runtime this project needs. The run

fails immediately and says so rather than waiting.

• The project does not build. A run uses the build that was made when the project was added or rebuilt; a

project listed as failed cannot be run until it builds.

• The licence limit. A tier has a maximum number of concurrent runs; when it is reached the run is refused

with that reason rather than queued indefinitely.

Each of these is recorded with the run, so the Execution History shows why a run did not produce a report.

Notifications

A run can carry a Slack message, an e-mailed report, or both. They are chosen per run rather than configured once and forgotten, so a nightly run can notify a channel while a run someone starts by hand does not.

The Slack message carries the per-step breakdown; the e-mail carries the same BDD report the page shows.

What the analysis is given

The AI analysis reads the runs themselves — dates, outcomes, durations, which steps failed and with what message — not the reports. It sees at most the twenty-five runs the scenario keeps, and it sees them as data: the prompt says so explicitly, so a step name that reads like an instruction is reported rather than obeyed.

Everything sent goes through Gheetah's outbound redactor first. A test that logged a token, a connection string or an authorization header does not hand it to the model provider because someone asked what the runs mean.

Getting an agent from installed to trusted

The walkthrough shows the download and the empty lists, because an agent has to be installed on a machine before there is anything to approve. These are the steps on that machine.

Install it

Download the build for the machine's operating system — Windows .exe, macOS .dmg, Linux .AppImage — or run the container image on a server with no desktop. The agent updates itself once it is connected, so this is done once per machine.

Point it at Gheetah

On first start the agent asks for the address of the Gheetah installation. It generates its own key, keeps the private half on the machine, and sends the public half with its request to join. The secret never travels.

Approve it

The request appears under Pending Register Agents List with the machine's name and operating system. Approving it is what makes the machine usable; until then it can connect and do nothing. A machine that should not be there is declined, and declined machines are listed separately rather than forgotten.

Use it

An approved agent appears in the Run Options target list beside the Docker servers, with how many runs it will take at once. It reports its own availability, so a laptop that is closed simply stops being offered.

Withdrawing a machine

Removing an agent stops new work reaching it immediately; runs already on it finish. Nothing has to be uninstalled on the machine itself for it to stop being trusted.

Things worth knowing about administration

Permissions are enforced on the server

What a group may do is checked on every request, by the server. The interface follows from the permissions — a person without execution permission is not shown a Run button — but the button is not what protects anything. This matters when Gheetah is driven from a pipeline with an API key: the key gets exactly the permissions of its group, and no more.

Groups, not people

Permissions are granted to groups and people are put into groups. On an installation using Azure AD, Google or SSO, directory group membership can be mapped onto Gheetah's groups, so joining a team in the directory is what grants access here.

The activity log

Sign-ins, project creation, runs, setting changes and administrative actions, each with who did it and when. The log grows without bound, so it is filtered and paged by the server, and a retention window can be set to prune it on a schedule.

Backup

Gheetah's own data — projects, users, groups, settings, execution history — can be exported and restored from Admin. On a JSON installation this is the Data folder; on a database it is a provider-level export, so a backup taken on one provider can be restored onto another.

The jobs dashboard

Background work — scheduled runs, retention, Docker host maintenance — runs through Hangfire, and its dashboard is reachable from Admin for anyone with administrative permission. It is where a job that did not run is explained.

The settings the walkthrough passed by

Mail

An SMTP configuration, used for two things: sending an execution report when a run asks for one, and sending a licence request to Gheetah. Several configurations can exist — a team's own relay for reports, the corporate one for anything leaving the building.

Slack

Incoming webhooks. A run can be told to notify one or more of them, and the message carries the scenario, the outcome and the failing steps. Webhooks are stored encrypted and are never shown again after they are saved.

Git Repos

The connections to GitHub, GitLab, Bitbucket and Azure DevOps that the Clone tab offers. Configured once, with a token stored encrypted, so nobody has to paste credentials into a project form.

Authentication

What was chosen during the first installation, changeable afterwards: local accounts, Azure AD, Google, or a generic OpenID Connect provider. Changing it does not delete the accounts that exist.

Package Feeds

Private NuGet and Maven registries. A feed configured here is offered when a project is built, so a build that needs a company package does not need the credentials written into the project.

API Reference — API Keys

Keys for driving Gheetah from a pipeline: start a run, read a result, list projects. Each key carries the permissions of the group it is issued for, so a key can be narrower than the person who created it.

JIRA Integration

Links scenarios and runs to JIRA issues, and pushes results back as comments or status transitions. An Enterprise installation can also publish the Forge plugin, which brings the same view inside JIRA itself.

Licence tiers

A tier includes everything the tiers below it have: the check is a rank comparison, so Enterprise has what Professional has, and both have what needs no licence at all.

Single sign-on is on that last list. It is chosen on the first screen of the setup wizard and nothing checks a licence for it — a Community installation signs in through Azure AD or Google exactly as a licensed one does.

A licence is a signed token: the tier and the features it unlocks cannot be edited into place, only replaced by a new token from Gheetah. The token names a term — one month, three, six, twelve, or, for Enterprise, one that does not expire — and the term is simply how far ahead the token’s expiry is set.

What Device Hub does when the licence allows it

Device Hub is where real Android and iOS devices become available to mobile scenarios. It needs a Professional licence; a Community installation sees the notice instead, which is why the walkthrough above stops there.

Nodes

A node is a machine with devices attached to it — a Mac with iPhones on USB, a Linux box with an Android farm. The node runs the Gheetah node agent, registers itself, and an administrator approves it the same way an execution agent is approved. Nothing is trusted because it asked.

Devices

Each device attached to an approved node appears with its model, operating system version and state. Gheetah talks to them through Appium, so the devices a mobile project can drive are the ones a node reports.

Control

A device can be driven from the browser — screen mirrored, taps and text sent — which is how a failing mobile step is investigated without walking over to the device. The same view records what was done, so a manual reproduction can be turned into a scenario.

This is the part that needs Enterprise, and it is a separate gate from the one above: registering nodes and seeing the devices on them is Professional, driving a device and running a Maestro flow on it is Enterprise.

What a Community installation can still do

Mobile projects can be generated, written and built without Device Hub. What needs the licence is attaching real devices to the installation; an emulator reachable from an execution target is not affected.

Writing and running scenarios without step definitions

The walkthrough stops at a project that is ready. What happens next is the part that makes a codeless project different from a written one.

Generating a scenario

Generate Scenario asks for a topic — "a customer completes the checkout", "login with an expired password" — and the model writes the scenario from it, using the project description and pre-prompt as context. What comes back is Gherkin in plain language: Given/When/Then that name what the user does, not which selector to click.

The scenario is editable afterwards. A model that misunderstood the product is corrected by rewriting a line, not by regenerating and hoping.

New Scenario skips the model entirely and lets you write those same plain-language steps yourself. This is the usual path once a team knows what it wants: the model is for the first draft and for filling gaps.

Running one

A codeless scenario is executed by the model driving the application. It reads the step, looks at the page, decides what to do and does it — clicking, typing, waiting — then checks the expectation the step describes. There is no step-definition layer to write, and nothing breaks when a selector changes.

It runs on the same execution targets a written project uses, and produces the same step-by-step report, so a mixed estate is read the same way whichever kind of project produced the result.

What it costs, and when to use which

Every step is a call to the model, so a codeless run is slower and costs per run in a way a compiled test does not. That trade decides where each kind belongs:

• Codeless for exploratory coverage, for a product whose interface is still moving, and for the scenarios a

non-developer needs to own end to end.

• Written (C#, Java, Playwright) for the suite that runs on every commit, where speed and determinism matter

more than flexibility.

Most teams end up with both, which is why they sit side by side and report the same way.

Which models can do it

Driving an interface needs a model with computer use: Claude and Gemini offer it, and a custom endpoint does if it supports the same. The other providers can still be registered for the technical side — generating step definitions and code — which is what the Agent Mode field on a provider decides.

The parts of the editor this walkthrough did not need

The flow above takes one change from an empty file to a merged pull request. Around it are the choices an installation makes once, and the paths a single person on a fresh instance never reaches.

Who can change what

Reading the editor needs the Editor permission, which Administrators, Leads and Runners all have. Everything that writes — saving a file, creating or renaming or deleting one, committing, switching branches, pushing, raising or merging a pull request — is refused to anyone who is not an Administrator or a Lead. A Runner therefore opens the same editor, reads the same diffs, and is told no if they try to change something. This is enforced on the server, not by hiding buttons.

If the installation turns on project ownership, the editor additionally only opens projects the signed-in user owns.

Reviewing when there is more than one of you

On an instance with a single Administrator, the person who raises a pull request may approve and merge it — otherwise nothing could ever be merged. As soon as there is a second Administrator or Lead, that stops:

• the author can no longer approve their own request;
• if reviewers are assigned, the request has to be Approved before it can be merged;
• a request with an Active comment on it cannot be merged at all, whoever left it. A comment is resolved from

the thread it lives in, where its state can be set to Resolved or Won't Fix, and reactivated later if the answer was not good enough.

An installation can also require the merge to build before it is allowed to stand. Merge & Build performs the merge in a temporary working copy, builds it, and only keeps it if the build succeeds.

Committing safely

Two things happen to every commit made from the editor, and neither can be turned off from inside it:

• Build output, package directories, .env files, key files and the rest of the exclusion list are never staged,

so a commit from the editor cannot accidentally carry bin/, obj/ or node_modules/ into the repository.

• The staged content is scanned for secrets — provider tokens, access keys, private-key headers. A file that

looks like it contains one is left out, and a commit that would consist of nothing else is refused with the reason.

Branch protection is separate and set by the installation: a branch on the protected list refuses direct pushes from anyone.

Working with a remote

A project can stay local. The commit still happens, the pull request still works, and the history is Gheetah's own — nothing needs a hosting account.

Attaching a remote is done from the Remote tab, either by choosing a repository configured in Settings → Git Repos (GitHub, Azure DevOps or GitLab, with the credentials held once and centrally) or by pasting a URL. The URL is checked before it is accepted: HTTPS only, no credentials embedded in it, no loopback or private-network hosts, and the host has to belong to the provider that was chosen. Once a remote is attached, Push and Pull move the branch between the working copy and it, and a pull that cannot be fast-forwarded reports the conflicting files rather than guessing.

Jumping to the code behind a step

Ctrl+Click on a step in a .feature file — or Go to Step Definition from the right-click menu — opens the class that binds it and scrolls to the line. It reads the project's own bindings, so it works in a project that arrived from a repository exactly as it does in a generated one, and it is how a scenario and its implementation stay in the same place in your head.

What the editor deliberately does not do

The Output panel below the editor shows what the server is streaming about this project — a build, a merge build — and nothing else. There is no shell: the editor changes files and drives Git, and running anything is the execution target's job.