Your First Project

A project is a git repository RoboCo is allowed to work on, plus the configuration that tells the company how to build and check it. Until you register one, the agents have nowhere to put their work. You register projects in the panel under Workstation → Projects → New.

What a project needs

Field	What it is
Name	Human-readable label for the repo.
Slug	URL-safe short name. It becomes the top of the workspace path (`{slug}/{team}/{agent}/`) and shows up in branch names.
Git URL	The clone URL. HTTPS is the common case and requires a token (below), unless the project is bound to a GitHub App installation instead — see GitHub App authentication.
Forge	Which forge API serves PR/CI/review operations: GitHub, Gitea, or GitLab. See Choosing a forge.
Git token	A personal access token for that forge, stored encrypted. Required for private or HTTPS repos — see The git token.
Assigned cell	Which delivery cell owns this repo: Backend, Frontend, or UX/UI.
Default branch	The branch PRs ultimately target (or the first rung of an environment ladder, if you configure one). Read the default-branch gotcha before you save.
Protected branches (optional)	Extra branch names, beyond the always-protected `master`/`main`, the fleet refuses to rebase onto or force-push over as a task's own branch. See Protecting extra branches.
Monthly Budget (USD) (optional)	A calendar-month spend cap across the project's tasks — see Task & project cost budgets.
Gate commands (optional)	Per-project test / lint / format / typecheck / build commands, and a fast pre-submit `quality_command`. See Gate commands.

Choosing a forge

RoboCo talks to three forges through the same set of PR/CI/review operations — GitHub, Gitea, and GitLab are all first-class, not GitHub-plus-afterthoughts. The Forge field in the project dialog picks which one:

Auto-detect covers github.com and gitlab.com — leave it on Auto-detect for either and RoboCo figures it out from the Git URL's host.
GitHub / GitHub Enterprise — the default. For a GHE instance, also set ROBOCO_GITHUB_API_BASE_URL to your instance's API base (see the environment reference).
Gitea (self-hosted) — set this explicitly for any Gitea instance, since there's no public gitea.com to auto-detect against. Works out of the box with a plain-http LAN instance too — RoboCo matches whatever scheme your Git URL uses, no extra configuration needed.
GitLab (gitlab.com / self-hosted) — auto-detects for gitlab.com; set it explicitly for a self-hosted GitLab instance, LAN or otherwise.

Whichever forge you pick, everything else on this page — the token, the default branch, gate commands, the workspace clone — works the same way. Cloning, branching, committing, and pushing are plain git and never cared which forge a repo lives on; only the PR-open/CI-read/review calls route through the forge-specific API.

The git token

Agents clone your repository and open pull requests (or merge requests, on GitLab) on it, so they need a personal access token with permission to do that, from whichever forge you picked above.

Scopes: the token needs repository read/write access (to clone and push branches) and pull/merge-request read/write access (to open and merge PRs). On GitHub, a classic repo-scoped token works, or a fine-grained token with Contents: Read and write and Pull requests: Read and write. On Gitea, a classic personal access token with repository scope. On GitLab, a personal access token with the api scope.
It's encrypted and write-only. The token is encrypted at rest the moment you save it (with your ROBOCO_ENCRYPTION_KEY) and the API never returns it — the panel only shows whether a token is set, not its value.
Rotating or clearing it: in Edit Project, entering a new token replaces it, an empty field clears it, and leaving it untouched keeps the current one.

HTTPS without a token fails

If you give an HTTPS Git URL and no token, the clone fails — agents can't reach the repo. Set the token when you create the project.

The encryption key is load-bearing

Every stored project token is encrypted with ROBOCO_ENCRYPTION_KEY. If you ever change that key, all stored tokens become undecryptable and you'll have to re-enter every one. Pick it once at install and keep it backed up.

GitHub App authentication

A GitHub project has a second, token-free auth path: bind it to an installation of a GitHub App you've configured on Settings → GitHub App (App id + private key, entered once). Once that's set up:

The New Project dialog's Select repo button lists the App's installations and repositories — pick one and both the Git URL and the installation binding are filled in for you, no manual token entry.
An existing project can bind or unbind the same way from Edit Project.
Bound git operations mint a short-lived installation token instead of using the project's stored PAT, and commits/PR reviews attribute to the App's own bot identity. Any minting failure (App not configured, installation revoked, a network hiccup) falls back to the project's own PAT automatically — set both and a GitHub App hiccup never bricks git operations for that project.
Unbinding (clearing the installation in Edit Project) reverts to the PAT below, with no other change.

This is GitHub-only — Gitea and GitLab projects always use the token path above.

Protecting extra branches

Beyond the hardcoded floor (master/main, always protected), you can name extra Protected Branches in the project dialog — a chips editor: type a name and press Enter or comma to add it, click the × to remove. A branch on this list is refused as a rebase target and refused a force-push as a task's own synced branch, matched exactly and case-sensitively. Every remote branch delete (task-branch cleanup, the stale-branch sweep, a merged PR's source-branch cleanup) additionally refuses any environment-ladder rung, even one not explicitly listed here.

The default-branch gotcha

The Create Project dialog defaults the branch to main, but several places in the backend assume master. Set this field explicitly to match your repository's real default branch (main or master) rather than trusting the pre-filled value. Getting it wrong is the most common first-run snag — branches get cut from, and PRs target, the wrong base.

Gate commands

A developer agent runs a quality gate against its own work before it submits for QA. By default that's a sensible lint + typecheck pair, but you'll get far better results by pointing RoboCo at your repository's real checks:

quality_command — the fast pre-submit gate, run at the moment an agent says it's done (for example make gate). If you set this, it replaces the default lint/typecheck pair. Keep it fast; it runs on every submission.
test_command, lint_command, format_command, typecheck_command, build_command — the individual commands for the cell's QA and CI steps.

Setting these so they mirror what you would run locally is the single biggest lever on output quality: the company gates itself exactly the way you would.

Sandboxing agents away from a repo

If you want to make sure agents can never point a project at a particular repository — RoboCo's own source, say, during a test run — set ROBOCO_PROTECTED_GIT_URLS to a comma-separated list of URL substrings. Creating or updating a project whose Git URL matches one is rejected.

What happens under the hood

You don't have to manage any of this, but it's worth knowing what registering a project sets in motion:

The first time an agent is assigned work on the project, RoboCo clones the repo into that agent's own workspace under ROBOCO_WORKSPACES_ROOT (default /data/workspaces). Every agent gets its own clone, so they work in parallel without stepping on each other. That directory is the disk to provision and back up.
Right after cloning, RoboCo scrubs the token out of the clone's git config and verifies no token byte survived anywhere under .git/ — destroying the workspace if one did. Your PAT never lives inside an agent container.

→ Your first task — hand the company something to build.

llms.txt