mirror of
https://github.com/rennf93/roboco.git
synced 2026-08-03 07:23:24 +02:00
Renn F
2fb63fed1f
Build a complete user-facing documentation site (MkDocs Material) under docs/, served at roboco.dev/docs via a new gh-pages deploy workflow. - Sections: Get Started, The Company, the Tour, Operating the Panel, Choosing & Running Models, Cost & Observability, Optional Subsystems, Configure & Deploy, API Reference, Troubleshooting & Security (55 pages). - mkdocs.yml (Material theme; excludes the agent-facing rag/ corpus, internal scratch, and orphaned stub trees) and .github/workflows/docs.yml (mkdocs gh-deploy to gh-pages). - Retire the stale root usage.md and deployment.md to redirect stubs into the site. - Fix the docs tooling: add the pymarkdownlnt dependency + .pymarkdown.json, run serve-docs/lint-docs/fix-docs under the docs extra, add a build-docs strict gate. - Fix the roboco console-script entry point (cli, not the un-awaited async main). - README: correct the project-structure tree (optimal.py, alembic) and link the docs site.
57 lines
4.5 KiB
Markdown
57 lines
4.5 KiB
Markdown
# Pitch Auto-Provisioning
|
|
|
|
Your Board can propose new products, not just deliver the ones you hand it. A **Pitch** (title, problem, proposed solution, target cells) is drafted by the Product Owner or Head of Marketing and lands in **Business → Pitches** for your decision. When you approve a pitch and provisioning is configured, RoboCo turns that approval into real infrastructure: one private GitHub repo per target cell, registered as Projects, with a Main-PM build task seeded into the normal delivery lifecycle. This is the only place in the whole system that *creates* GitHub repos — everywhere else clones, branches, and opens PRs against repos that already exist.
|
|
|
|
## Default state
|
|
|
|
The master switch `ROBOCO_PROVISIONING_ENABLED` defaults to `true`, but the capability is **inert unless a token and an org are both set**. With no `ROBOCO_PROVISIONING_TOKEN` and no `ROBOCO_PROVISIONING_ORG`, approving a pitch raises `ProvisioningDisabledError` and creates nothing. So out of the box, pitch approval is a no-op until you point it at a GitHub org. The Settings → Feature Flags card exposes the toggle ("Auto-provision projects from approved pitches"), but the toggle alone does nothing without the credentials.
|
|
|
|
## Enable it
|
|
|
|
1. **Create a GitHub PAT** with `repo` + org-admin scope, in the org you want repos created in.
|
|
2. **Set the credentials** in your deploy environment:
|
|
|
|
| Env var | Default | Purpose |
|
|
|---------|---------|---------|
|
|
| `ROBOCO_PROVISIONING_ENABLED` | `true` | Master switch. Inert regardless unless token + org are also set. |
|
|
| `ROBOCO_PROVISIONING_TOKEN` | (empty) | GitHub PAT used to create repos. Needs `repo` + org-admin scope. **Server-side only.** |
|
|
| `ROBOCO_PROVISIONING_ORG` | (empty) | GitHub organization where new repos are created. |
|
|
| `ROBOCO_PROVISIONING_REPO_PRIVATE` | `true` | Whether provisioned repos are created private. |
|
|
| `ROBOCO_GITHUB_API_BASE_URL` | `https://api.github.com` | REST API base — override for GitHub Enterprise. |
|
|
| `ROBOCO_PROVISIONING_TIMEOUT_SECONDS` | `30.0` | Per-request timeout for GitHub provisioning calls. |
|
|
|
|
3. Confirm the **Settings → Feature Flags** toggle is on (it falls back to the config default if unset).
|
|
4. **Restart the backend.**
|
|
|
|
The token and org live only in server-side config — like the research key, they are never injected into an agent container.
|
|
|
|
## What changes when it's on
|
|
|
|
When you approve a pitch in **Business → Pitches**, `PitchService` runs the provisioning sequence:
|
|
|
|
```mermaid
|
|
flowchart LR
|
|
A[Board drafts Pitch] --> B[CEO approves]
|
|
B --> C{token + org set?}
|
|
C -->|no| D[ProvisioningDisabledError<br/>nothing created]
|
|
C -->|yes| E[Create 1 private repo<br/>per target cell]
|
|
E --> F[Register each as a Project<br/>+ a Product if multi-cell]
|
|
F --> G[Seed a Main-PM build task<br/>source=pitch, confirmed_by_human=true]
|
|
G --> H[Normal delivery lifecycle]
|
|
```
|
|
|
|
A single-cell pitch produces one repo named after the slug; a multi-cell pitch produces one repo per cell (`{slug}-{cell}`) and a **Product** mapping each cell to its repo, which is what drives the Main-PM integration-branch model. The seeded task is a real PENDING task assigned to the Main PM and flows through the same lifecycle as any other work.
|
|
|
|
## The partial-failure caveat
|
|
|
|
!!! warning "A failed approval can leave orphan repos"
|
|
GitHub repo creation is an un-rollback-able side effect. If provisioning fails partway — say it creates the first cell's repo and then errors on the second — the database writes roll back (the approval route does not commit), but **the repos already created on GitHub remain**. A re-approval will then collide on the repo name and fail. You resolve this manually: delete or rename the orphaned repo(s) on GitHub, or finish wiring them up by hand, before re-approving. RoboCo deliberately does not auto-delete repos it created, so it can never destroy work.
|
|
|
|
## Required extra config
|
|
|
|
A GitHub PAT (`repo` + org-admin scope) and the target org are mandatory — there is no provisioning without them. For GitHub Enterprise, also set `ROBOCO_GITHUB_API_BASE_URL`. Provisioning writes Project / Product / task rows, so make sure your migrations are current (`alembic upgrade head`).
|
|
|
|
## Next
|
|
|
|
→ **[Projects and products](../panel/projects-and-products.md)** — what a Project and a multi-cell Product are. → **[The merge model](../company/merge-model.md)** — how the Main PM cuts one integration branch per repo. → **[The business workflow](../how-to/05-the-business-workflow.md)** — drafting and reviewing pitches.
|