# Connect an existing project

Connect an existing project when the repository already exists in GitHub and should become the TestVibe workspace.

The repository may already contain tests, or it may be an application repository where TestVibe should add test files and workflow setup.

## When To Connect Existing

| Situation                                  | Why this path fits                                               |
| ------------------------------------------ | ---------------------------------------------------------------- |
| The app repository already exists          | You want test files and workflows beside the application code.   |
| A dedicated test repository already exists | You want TestVibe to use a repository your team already created. |
| Some test files already exist              | TestVibe can read existing feature and Playwright files.         |
| Your team already manages GitHub access    | You only need to add or confirm TestVibe setup.                  |

## Steps

1. Sign in to TestVibe.
2. Select the GitHub App installation for the repository owner.
3. Select the team if TestVibe asks for one.
4. Choose the existing repository.
5. Wait for TestVibe to load the workspace.
6. Review repository settings before generating or running tests.

If TestVibe asks to add or update setup files, review the change and continue if the repository should be managed by TestVibe.

## What TestVibe Looks For

TestVibe may use repository content such as:

| Content                  | How TestVibe uses it                                          |
| ------------------------ | ------------------------------------------------------------- |
| Feature files            | Shows readable Gherkin test intent in the Test Suite.         |
| Playwright files         | Runs generated or existing browser automation.                |
| Configuration files      | Controls browser, viewport, reporting, and run behavior.      |
| TestVibe settings        | Stores project defaults such as framework, agent, and runner. |
| GitHub Actions workflows | Executes generation and test runs in GitHub.                  |

If some pieces are missing, TestVibe can still help you set up the project. The exact setup needed depends on how the repository is organized.

## Before Running Tests

Confirm these settings:

| Setting               | Why it matters                                                      |
| --------------------- | ------------------------------------------------------------------- |
| Default Test URL      | The runner needs a reachable target site.                           |
| Website framework     | Helps generation produce better instructions and selectors.         |
| AI agent and API key  | Required for AI generation when using a provider that needs a key.  |
| Runner                | GitHub Actions needs a matching runner with access to the site.     |
| Secrets and variables | Login, test data, and provider settings may be needed by workflows. |

See [Configure site URL and repository settings](/workspace/configure-site-url-and-repository.md).

## If Existing Tests Do Not Appear

Check that:

* the repository is the one you expected
* the files are on the branch TestVibe is using
* feature files use the `.feature` extension
* Playwright files are stored in the expected test areas
* the GitHub App has access to the repository

For setup concepts, see [Key concepts](/readme/key-concepts.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/workspace/connect-existing-project.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.