---
name: onboarding-repository
description: "Choose where a new project's agent code lives: a new or existing GitHub repository, or one Introspection hosts. Connects GitHub and registers the repository when chosen. The first onboarding step."
metadata:
  min-cli-version: "0.76.0"
  next: "onboarding-issues"
---

# Onboarding: source

## Check

- **GitHub:** `introspection integrations repositories --type github --query "length(records)"` succeeds when the organization's GitHub App is installed, counting the repositories it reaches; it fails with "no active GitHub integration" when it isn't.
- **Registered repositories:** `introspection repositories list -o table`.

If a repository is already registered, say which in one line and go to onboarding-issues.

## Ask

One question with the question tool, header "Code", whatever the check found: GitHub not being connected yet is not a choice, so never pick Introspection for the owner. Two options, in this order, labelled exactly "GitHub" and "Introspection":

- **GitHub:** "Your agent's code lives in a GitHub repository you own; changes come as pull requests."
- **Introspection:** "Introspection hosts the repository for you; nothing to connect."

Don't ask whether to start from a template here: that is build's question.

## Connect

- **GitHub, not installed:** `introspection_open` with `{kind: "integration", provider: "github"}`, `wait: true`, reason "So your agent's code can live in your GitHub" (on a host without it, the dashboard, as onboarding says). Call it right after the answer, with nothing said in between. After `connected`, check the install with the command above, without saying so unless it fails.
- **GitHub, installed:** nothing more to do.
- **Introspection:** nothing to connect. Deploy creates the hosted repository itself, with no further question, since this choice was the owner's yes.
- **Later:** record nothing.

## Choose the GitHub repository

Once GitHub is connected, ask one question with the question tool, header "Repository": **New repository** ("Create one on GitHub for this agent") or **Existing repository** ("Use one the Introspection GitHub App already reaches").

- **New repository:** ask its name, suggesting one from what the agent is for (the owner can change it). Then `introspection_open` with `{kind: "repository", provider: "github", name: "<name>"}`, `wait: true`, reason "So your agent's code lives in your new repository", on its own in a turn: GitHub's new-repository page opens pre-filled, and `connected` means the owner created it and it is registered with the project. In a terminal without the tool, `introspection open --repository --name <name> --wait`.
- **Existing repository:** offer what `introspection integrations repositories --type github --query "records[].full_name"` lists, most recently pushed first, as options of a question (the owner can type another). Register the one they pick with the same `introspection_open` target, named without its owner: a repository the App already reaches is registered with no GitHub page. One the App can't see needs the organization to give the App access to it, so say so and ask again once it has.

Confirm either with `introspection repositories list -o table`. Don't push to it here: the code lives only in the session until deploy pushes there.

## Done when

The owner has a repository choice (a registered GitHub repository, or Introspection), or said later. Keep the choice for the rest of the conversation: deploy pushes to that GitHub repository, or creates the hosted one, when it creates the first runtime, and until then the code lives only in the session, so never tell the owner it will live anywhere else, and never tell them new agents must be hosted. Go to `onboarding-issues`.