> ## Documentation Index
> Fetch the complete documentation index at: https://docs.stably.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Bring Your Own Repo

> Connect your existing GitHub or GitLab repository to Stably for test case management and the web editor.

<Info>
  **This integration is only needed if you want to use Stably's [web editor](/stably2/web-quickstart).** If you just want to run your existing tests in CI/CD (GitHub Actions, GitLab CI, etc.), you don't need this — see our [CI/CD guide](/run-tests/cli-in-ci) instead.
</Info>

Connect your existing repository so Stably can sync test cases between your codebase and the [web editor](/stably2/web-quickstart). This lets you create, edit, and manage tests from both the Stably dashboard and your local development environment.

## Why bring your own repo?

* **Edit anywhere, stay in sync** — Make changes in your IDE, Stably's [web editor](/stably2/web-quickstart), or CLI—everything syncs to the same repository automatically
* **Existing tests & rules** — Already have Playwright tests, custom configurations, or team conventions? Stably works with what you have

<Note>
  **Just need CI/CD?** You can run Stably tests in any CI/CD pipeline without connecting a repository here. See the [CI/CD integration guide](/run-tests/cli-in-ci) for GitHub Actions, GitLab CI, CircleCI, Jenkins, and more.
</Note>

## Supported providers

<Tabs>
  <Tab title="GitHub">
    GitHub integration uses a GitHub App for authentication. This provides bot-based commits by default with optional personal attribution.

    <Tip>
      This setup connects your repo to Stably's [web editor](/stably2/web-quickstart) and test case management. To run tests in GitHub Actions instead, see the [GitHub Actions CI guide](/run-tests/github-actions).
    </Tip>

    ### Connect a GitHub repository

    <Steps>
      <Step title="Install the GitHub App">
        Click **Install GitHub App** to authorize Stably to access your repositories.
      </Step>

      <Step title="Configure your repository">
        Select your repository and configure the connection settings:

        <Frame>
          <img src="https://mintcdn.com/stablyai/0tksrTqimWCps9n5/images/stably2/bring-your-own-repo.png?fit=max&auto=format&n=0tksrTqimWCps9n5&q=85&s=87e5aab54efc46c01defc32db50481a8" alt="Stably project creation showing the option to connect an existing GitHub repository" width="751" height="621" data-path="images/stably2/bring-your-own-repo.png" />
        </Frame>

        <br />

        <Accordion title="Configuration settings">
          * **Repository** — Select the GitHub repository to connect
          * **Branch** — Choose the branch to sync with (e.g., `main`, `develop`)
          * **Working Directory** — Relative path from repo root where tests live (e.g., `tests/e2e`). Leave empty for repo root. Stably auto-detects existing `playwright.config` files.
          * **Package Manager** — Select your package manager: `npm`, `pnpm`, `yarn`, or `bun`
          * **Publish Behavior** — Choose how changes are published:
            * **Create Pull Request** — Creates a PR for review before merging
            * **Push to main branch directly** — Pushes changes directly to the main branch
        </Accordion>
      </Step>

      <Step title="Start testing">
        Create tests with the web editor or CLI—they all sync to your repository automatically.
      </Step>
    </Steps>

    ### PR authorship (GitHub)

    By default, PRs created by Stably show the Stably bot as the author. You can connect your personal GitHub account so PRs show you as the author instead.

    To enable: go to **Settings > Git** and click **Connect GitHub** in the PR Authorship section.
  </Tab>

  <Tab title="GitLab">
    GitLab integration uses OAuth to connect your GitLab account. Merge requests are attributed to your account.

    <Tip>
      This setup connects your repo to Stably's [web editor](/stably2/web-quickstart) and test case management. To run tests in GitLab CI instead, see the [GitLab CI guide](/run-tests/run-tests-on-gitlab) or the general [CI/CD guide](/run-tests/cli-in-ci).
    </Tip>

    ### Connect a GitLab repository

    <Steps>
      <Step title="Authorize GitLab">
        Click **Authorize GitLab** to connect Stably to your GitLab account.
      </Step>

      <Step title="Configure your repository">
        Select your repository and configure the connection settings:

        <Frame>
          <img src="https://mintcdn.com/stablyai/0tksrTqimWCps9n5/images/stably2/bring-your-own-repo.png?fit=max&auto=format&n=0tksrTqimWCps9n5&q=85&s=87e5aab54efc46c01defc32db50481a8" alt="Stably project creation showing the option to connect a repository" width="751" height="621" data-path="images/stably2/bring-your-own-repo.png" />
        </Frame>

        <br />

        <Accordion title="Configuration settings">
          * **Repository** — Select the GitLab repository to connect
          * **Branch** — Choose the branch to sync with (e.g., `main`, `develop`)
          * **Working Directory** — Relative path from repo root where tests live (e.g., `tests/e2e`). Leave empty for repo root. Stably auto-detects existing `playwright.config` files.
          * **Package Manager** — Select your package manager: `npm`, `pnpm`, `yarn`, or `bun`
          * **Publish Behavior** — Choose how changes are published:
            * **Create Merge Request** — Creates an MR for review before merging
            * **Push to main branch directly** — Pushes changes directly to the main branch
        </Accordion>
      </Step>

      <Step title="Start testing">
        Create tests with the web editor or CLI—they all sync to your repository automatically.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## Migrating an existing Stably project

If you already have a Stably project using the managed repository and want to switch to your own:

<Steps>
  <Step title="Switch to Agent 2.0">
    Make sure your project is using **Agent 2.0**. You can check this in your project settings.
  </Step>

  <Step title="Export your tests">
    Go to **Settings > Git** to export your existing tests. This creates files you can import into your own repository.
  </Step>

  <Step title="Connect your repository">
    Follow the GitHub or GitLab setup steps above to connect your repository.
  </Step>
</Steps>

## Troubleshooting

<AccordionGroup>
  <Accordion title="GitLab authentication failed">
    If you see "GitLab authentication failed", your OAuth token may have expired. Re-authorize GitLab in your project settings.
  </Accordion>

  <Accordion title="Missing repository permissions">
    Make sure your GitLab account has write access to the repository you're trying to connect.
  </Accordion>
</AccordionGroup>

## Compatibility

* **Git providers**: GitHub, GitLab
* **Works with any web application** — Supports React, Angular, .NET, and any backend framework (e.g., Python, Rust). Our tests simulate real user behavior, so we're technology agnostic.

## Next steps

<CardGroup cols={2}>
  <Card title="Web Editor Quickstart" icon="browser" href="/stably2/web-quickstart">
    Create your first test in the web editor
  </Card>

  <Card title="CLI Quickstart" icon="terminal" href="/stably-cli/quickstart">
    Generate tests from your terminal
  </Card>

  <Card title="CI/CD Integration" icon="rotate" href="/run-tests/cli-in-ci">
    Run tests in your CI/CD pipeline (no repo connection needed)
  </Card>

  <Card title="GitHub Actions" icon="github" href="/run-tests/github-actions">
    Run tests with the Stably GitHub Action
  </Card>
</CardGroup>