First-Run Setup
Get a project running on stages: connect a tracker, map one status, add a card, pick a model, and run.
Preview. Stages 1.0 is built and merged but not deployed yet. Names, screens and defaults on this page can change before release.
A new project needs five things before it can run: a tracker, one mapped status, a card for that status, a model, and a published workflow. You do not need to configure everything. Start with one status and one card, then add stages, statuses and cards later without touching the workflow.
The project's Stages page shows a checklist titled Get this project running that reads your project's real configuration. This page walks through the same steps.
Before you start
You need a Rensei organization and a project, and project admin access. If you have not signed in and linked your accounts yet, start with the Quickstart.
Link a tracker. Open the project's Settings, then Trackers, and link the issue tracker the project works from. A project can have more than one tracker; each gets its own status mapping.
The checklist step is Link a tracker. It is done when the project has at least one linked tracker.
Map one status to a stage. Open the project's Settings, then Stages. Under Tracker status mapping, pick a stage for one of your tracker's statuses. To get started, map the status where work is ready to be picked up to Backlog (key backlog, role intake).
Every mapped stage also needs one write status: the tracker status the platform sets when work moves into that stage. Choose one of the statuses you mapped to it. Select Save mapping.
The checklist step is Map a status to a stage. It is done when at least one status maps to an enabled stage and the mapping validates. If the saved mapping is invalid, the step shows the reason.
Details are on Stages and Roles.
Add a card. The Backlog stage ships with Development as its default card, so a status mapped to Backlog already has a card. To run a different card, or add one, open the stage with Edit (or Customize, if it is inherited) and use Add a card. Make it the default with the radio button, then Save cards.
Find more cards in the Marketplace, under Agents. See Skills for the Agents tab and Stage Cards for how a stage chooses between its cards.
The checklist step is Choose the card that runs. It is done when a mapped stage that can run work (role intake, inflight, review or rework) has a default card and is not disabled.
Pick a model. A run needs a model it can use. If none has been set, the checklist tells you which stage resolves no model.
- Connect a provider in Settings, then Integrations.
- Install a model for the org from the Marketplace, under Models.
- Choose the model for the stage or the card, or leave it as inherit to use the project's default.
See Model Access and Choosing Models.
The checklist step is Choose a model. It runs the same model resolution a real dispatch would, once for each runnable mapped stage, and reports the model each one resolves to.
Publish the workflow. Subscribe the project to the default SDLC workflow. The workflow stays the same as you add stages and cards.
The checklist step is Publish the workflow. It is done when the project has a published subscription to an official template. For the template that works with stages, see Upgrading to the Portable SDLC Template 4.0.0.
Run it. When every blocking step is done, the checklist reads This project is ready to run. Then do either:
- move an issue to the status you mapped; or
- mention the agent on an issue, naming a card on the stage if you want a specific one:
@rensei research What does the nightly import depend on?Credentials
The checklist has a Credentials row between the model and the workflow. It is informational: it tells you whether the project has a single default credential set. A project without one can still run, because runs use the project's credential bindings. Select Review on that row if you want to check them.
What happens to statuses you have not mapped
Only mapped statuses mean anything to the platform.
- An issue moving to an unmapped status does not start a run.
- A transition aimed at a stage that has no mapped status in your tracker leaves the issue where it is. For example, if you mapped only Backlog, then after Development finishes the issue is not moved to Review until you map Review and its write status.
Map more statuses as you want the issue to move.
Grow it later
Once the first run works, you can extend the setup without editing the workflow:
- add a card to a stage, such as Backlog Writer in Icebox;
- add a stage of your own, give it a role, and map a status to it;
- change where a stage sends work on success, failure, blocked or close;
- set models per stage or per card, or follow a model line;
- install models and skills for the org or the project.
Read the checklist from the API
GET /api/projects/{projectId}/stages/readinessThe response lists the six steps in order: tracker, mapping, card, model, credentials and workflow. Each has ok, a one-sentence detail and the settings page fixHref where it is fixed. Add trackerId to check one tracker's mapping. Any member of the project can read it, and it changes nothing.