mirror of https://github.com/rennf93/roboco.git synced 2026-08-03 07:23:24 +02:00

Files

T

Renn F 2fb63fed1f docs: add the user-facing MkDocs documentation site

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.

2026-06-22 15:53:00 +02:00

4.5 KiB

Raw Blame History

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

Create a GitHub PAT with repo + org-admin scope, in the org you want repos created in.

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.

Confirm the Settings → Feature Flags toggle is on (it falls back to the config default if unset).
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:

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).

→ Projects and products — what a Project and a multi-cell Product are. → The merge model — how the Main PM cuts one integration branch per repo. → The business workflow — drafting and reviewing pitches.

4.5 KiB Raw Blame History