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

# Start from a Repository

> Start an Onyx campaign from an existing git repository.

Onyx works with repositories you already own. It does not scaffold a new repository or move your code out of git.

## Start with the GitHub App

<Steps>
  <Step title="Open the app">
    Go to [app.onyxresearch.ai](https://app.onyxresearch.ai) and sign in.
  </Step>

  <Step title="Connect GitHub">
    In Settings → Integrations, click **Connect GitHub** to install or manage
    the Onyx GitHub App for the GitHub account or organization. The flow opens
    in a new tab and includes a GitHub user authorization step that verifies
    your account can access the installation; it finishes back on
    Settings → Integrations.
  </Step>

  <Step title="Choose a repository">
    Grant Onyx access to the repository. Onyx records repository metadata and keeps the default branch head fresh through GitHub repository sync.
  </Step>

  <Step title="Create the campaign">
    Use `/onyx ...` or `onyx campaign setup` from the local checkout. Pass `--project-path` when the research work is scoped to a subdirectory.
  </Step>
</Steps>

The GitHub App is used for repository selection, private repository access, installation metadata, webhook updates, repository sync, and code reads. Onyx does not store GitHub installation tokens. Internal project rows are created or reused automatically from campaign creation.

## Choose a Project Path

Set `projectPath` when only a subdirectory belongs to the research work.

Examples:

| Repository layout     | Project path       |
| --------------------- | ------------------ |
| Whole repository      | `""`               |
| App inside a monorepo | `apps/controller`  |
| Library package       | `packages/planner` |

Paths returned by the app are relative to `projectPath`, while GitHub code reads still happen against the full repository.

## Repository Sync Behavior

GitHub webhooks mark projects `not_synced` and schedule repository metadata sync. The exact source of code remains git, and file trees, blobs, and diffs are read from actual commits through GitHub.

This repository sync is distinct from research reporting. Campaigns, sessions, workers, experiments, summaries, and knowledge are written directly to the Onyx API by the CLI and worker commands. In the app, use the repository sync action for the tracked project when repository metadata looks stale.