# GitHub-hosted runners

GitHub-hosted runners are machines managed by GitHub. They are usually the easiest runner choice because your team does not need to install or maintain runner software.

For TestVibe, GitHub-hosted runners are a good default when your target site is reachable from the internet or from GitHub's runner environment.

## Common Hosted Labels

TestVibe can offer common hosted runner labels such as:

| Label            | Typical use                                                       |
| ---------------- | ----------------------------------------------------------------- |
| `ubuntu-latest`  | Default Linux runner for most Playwright test runs.               |
| `ubuntu-24.04`   | Specific Ubuntu version when you want a pinned Linux environment. |
| `windows-latest` | Windows runner for Windows-specific test requirements.            |
| `windows-2025`   | Specific Windows version when your team needs it.                 |
| `macos-latest`   | macOS runner for Apple-specific browser or platform needs.        |
| `macos-15`       | Specific macOS version when your team needs it.                   |

The exact hosted runner labels available to your repository can change over time in GitHub. Use the Runners settings page to choose the labels TestVibe shows for your project.

For GitHub's current hosted-runner reference, see [GitHub-hosted runners](https://docs.github.com/en/actions/concepts/runners/github-hosted-runners).

## When Hosted Runners Work Well

Hosted runners are usually best when:

| Need                          | Why hosted works                                                         |
| ----------------------------- | ------------------------------------------------------------------------ |
| Fast setup                    | GitHub manages the machine lifecycle.                                    |
| Public or staging target site | The runner can open the target URL without private network access.       |
| Standard Playwright setup     | Browser dependencies can be installed during the workflow.               |
| Occasional or elastic usage   | GitHub can provide runner capacity without your team operating machines. |

## When Hosted Runners May Not Work

A hosted runner may not be the right fit when:

| Limitation                                                   | What to use instead                                                                   |
| ------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
| The site is only available on a private network              | Use a self-hosted runner with network access.                                         |
| The site requires local-only services                        | Use a self-hosted runner on the same network or machine class.                        |
| Your tests need custom certificates, fonts, or tools         | Use a prepared self-hosted runner, or add setup steps if your workflow supports them. |
| Your organization requires controlled execution environments | Use an approved organization or self-hosted runner pool.                              |

## Practical Tips

* Start with `ubuntu-latest` for most projects.
* Use a specific OS version when you need predictable platform behavior.
* Confirm your target site URL works from outside your local machine.
* If tests fail before opening the site, check runner setup, dependencies, and workflow logs.

GitHub also documents runner selection in [Choosing the runner for a job](https://docs.github.com/en/actions/how-tos/write-workflows/choose-where-workflows-run/choose-the-runner-for-a-job).

For private environments, see [Self-hosted runners](/runners/self-hosted-runners.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/github-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.