# Private and non-public GitHub repositories

Agent docs index: /llms.txt

Wheelie's launch-preview private-repository support is deliberately conservative.
The public first-run path is green for the documented public GitHub source
smoke, not for arbitrary private repositories.

## Current support level

| Repository kind | Launch support | What Wheelie should return |
| --- | --- | --- |
| Documented public GitHub sample, for example `octocat/Hello-World` | `native` / `live` for source status | `wheelie integration connect github --repo octocat/Hello-World --json` returns a native connection receipt; `wheelie source status --repo octocat/Hello-World --json` returns source status without printing raw tokens. |
| Your public GitHub repo | Supported when your Wheelie credential or trusted-agent grant is scoped to that repo and the repo is publicly cloneable from a clean install | Source/working-copy commands either materialize/reopen the repo or fail with typed auth/grant/repo-binding fields. |
| Private or otherwise non-public GitHub repo | Launch-deferred unless the selected repo returns a mediated source-provider adapter or allowlist receipt | `source_provider_adapter_required` with `support_state: "requires_adapter"` is the correct safe outcome. |

Exact user-facing wording: **Private and other non-public GitHub repositories are
launch-deferred until Wheelie returns a mediated source-provider adapter or
allowlist receipt for the selected repo. If a command returns
`source_provider_adapter_required` / `requires_adapter`, use a public GitHub repo
or attach the mediated adapter path; do not paste raw provider tokens, SSH keys,
OAuth codes, cookies, private source dumps, or local credential-helper state.**

## Supported launch flow

Use this flow first, replacing the sample repo only with a repo that the current
Wheelie account and support state say is supported:

```bash
wheelie auth login
wheelie auth status --json
wheelie integration connect github --repo octocat/Hello-World --json
wheelie source status --repo octocat/Hello-World --json
wheelie work create --title "Update the README greeting" --json
wheelie work open-working-copy wheelie://work-items/<id> --repo octocat/Hello-World --launch pi --json
```

Read the JSON fields, not terminal prose. Safe fields include
`schema_version`, `schemaVersion`, `support_state`, `reason`, `next_action`,
`repo_ref`, `source_materialization`, `provider_mutation_performed`,
`raw_token_printed`, `work_item_ref`, `working_copy_id`, and `agent_session`.
For `--launch pi`, treat `support_state: "requires_adapter"` plus
`agent_session: null` as working-copy handoff only, not proof that Pi was
started.

## What to do for a private repo

1. Run `wheelie auth status --json` and confirm you are signed in with the
   intended account.
2. Run `wheelie integration connect github --repo <org>/<repo> --json`.
3. Run `wheelie source status --repo <org>/<repo> --json`.
4. If the receipt says `source_provider_adapter_required` or
   `support_state: "requires_adapter"`, stop. Use a public repo for the launch
   flow or ask support for the mediated private-source path.
5. Share only redacted typed fields with support: `reason`, `support_state`,
   `next_action`, operation refs, source refs, and work refs. Do not share raw
   source, private provider URLs, tokens, SSH keys, cookies, screenshots with
   secrets, or full terminal transcripts.

## Unsupported shortcuts

These are not safe workarounds and are not part of the public launch path:

- pasting a raw GitHub token, OAuth code, cookie, SSH private key, deploy key,
  or service-account JSON into a prompt, command argument, log, or support
  thread;
- relying on local provider CLI sessions, local SSH agent state, credential
  helpers, or a developer machine's private checkout as public Wheelie support
  evidence;
- describing GitHub connection success as proof that private source
  materialization is live;
- publishing private repository names, source bytes, diffs, provider URLs,
  capability URLs, or screenshots as launch evidence;
- using internal project overlays or raw provider/admin commands as user
  documentation.

## Related support docs

- [Quickstart](./quickstart.md)
- [CLI support map](./cli.md)
- [Support levels](./support-levels.md)
- [Launch support and friendly error states](./support.md)