# Self-hosted runners

Self-hosted runners are machines your team registers with GitHub Actions. TestVibe can use them when their labels match the runner setting for the repository.

Self-hosted runners are useful when GitHub-hosted runners cannot reach your application or when your team needs a controlled environment.

For GitHub's overview of the feature, see [Self-hosted runners](https://docs.github.com/en/actions/concepts/runners/self-hosted-runners).

## When To Use A Self-Hosted Runner

Use a self-hosted runner when:

| Need                    | Why self-hosted helps                                                   |
| ----------------------- | ----------------------------------------------------------------------- |
| Private target site     | The runner can run inside the network that hosts your app.              |
| VPN or firewall access  | The runner can use your team's approved network path.                   |
| Custom dependencies     | Your team can install required tools, certificates, fonts, or services. |
| Stable environment      | The same runner setup can be reused across generation and test runs.    |
| Compliance requirements | Your organization controls where automation executes.                   |

## What The Runner Needs

Before using a self-hosted runner with TestVibe, confirm:

| Requirement             | What to check                                                     |
| ----------------------- | ----------------------------------------------------------------- |
| GitHub registration     | The runner appears in the repository or organization runner list. |
| Online status           | The runner service is running and connected to GitHub.            |
| Matching labels         | The runner labels match the labels selected in TestVibe.          |
| Site access             | The runner machine can open the target site URL.                  |
| Browser support         | Playwright can install or use the browsers needed for your tests. |
| Secrets and permissions | The workflow can access the repository secrets it needs.          |

## Labels Matter

Self-hosted runners commonly include the `self-hosted` label plus operating-system or custom labels. Your organization may also add labels such as a team name, environment name, or runner pool name.

GitHub only assigns work to a self-hosted runner when every required label matches. If TestVibe is set to use labels that no online runner has, the workflow can stay queued.

For GitHub's label and group routing details, see [Using self-hosted runners in a workflow](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/use-in-a-workflow).

## Security Notes

Self-hosted runners can access the network and files available to the machine where they run. Work with your GitHub or platform administrator to make sure:

| Area              | Recommendation                                                    |
| ----------------- | ----------------------------------------------------------------- |
| Repository access | Only trusted repositories use the runner.                         |
| Network access    | The runner can reach what tests need, but no more than necessary. |
| Secrets           | Repository and organization secrets are scoped carefully.         |
| Updates           | Runner software, browsers, and system packages stay current.      |

## Setup In TestVibe

After your runner exists in GitHub:

1. Open the repository in TestVibe.
2. Go to **Settings** > **Runners**.
3. Select **Refresh runners** if the runner is new.
4. Find the runner or label set.
5. Select **Set as default runner**.
6. Run a small test to confirm the runner picks up work and can reach the site.

If the runner does not exist yet, GitHub's [Adding self-hosted runners](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/add-runners) page walks through registering a repository, organization, or enterprise runner. For organization access policies, see [Managing access to self-hosted runners using groups](https://docs.github.com/en/actions/how-tos/manage-runners/self-hosted-runners/manage-access).

For step-by-step TestVibe settings help, see [Set the default runner](/runners/set-default-runner.md).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.testvibe.com/runners/self-hosted-runners.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.