Phase 1 - Caproni - Deliver an end-to-end development flow to support onboarding
### Participants
* @kkloss
* @gitlab.mschoenlaub
* @nao.hashizume
* @andrewn
* @hmuralidhar
* @vishal.s.patel
### **Description**
The goal of this epic is to deliver a full development flow for engineers at GitLab. At this stage, Caproni will support onboarding and development but there will be known rough edges. Following iterations will work directly with teams to understand their specific needs and extend Caproni to support them.
This epic builds on the demo delivered in early March, and [incorporates any significant feedback](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/work_items/4) received.
At the end of this epic, users will be able to:
* **Set up and manage development environments** - Use the Caproni CLI to easily create, configure, and manage Kubernetes clusters for local development
* **Run multiple services simultaneously** - Manage multi-process development workflows to work with the GitLab monolith and satellite services (OpenBao & Gitaly) at the same time
* **Follow a streamlined development workflow** - Access a golden path workflow optimized for daily development tasks, including edit-mode and local testing
### **Business Case**
Self-managed customers deploy on Kubernetes. Developers encountering K8s for the first time in CI or customer environments leads to defect escapes and poor upgrade experiences. Developing locally on K8s creates environment parity from first line of code.
### **Success Criteria**
- [ ] Caproni onboarding flow is stable and documented
- [ ] Edit-mode enables stable development flows, supported by local testing
- [ ] As far as possible, Production CNG images and Helm charts are used to power Caproni. All workarounds have an issue to track the work to remove
* [ ] Caproni meets performance and development workflow criteria:
* [ ] Platform runs GitLab core services on 32GB MacBook with acceptable performance
* [ ] Edit-mode hot-reload achieves \<10 second feedback loop for Rails changes
* [ ] Startup time under 5 minutes
- [ ] Caproni availability is announced in #development channels
### Architectural Design
This section will be replaced with a link to documentation before the epic is closed
```mermaid
flowchart TB
subgraph Developer["Developer Workstation"]
subgraph EditMode["Edit Mode Services (Local)"]
mirrord["mirrord exec"]
puma["webservice (puma)"]
workhorse["workhorse"]
vite["vite/webpack"]
mirrord --> puma
end
subgraph Cluster["Local K8s Cluster (Colima + k3s)"]
webservice["webservice pod"]
sidekiq["sidekiq"]
gitaly["gitaly"]
postgres["postgresql"]
redis["redis"]
minio["minio"]
end
subgraph CLI["Caproni CLI (Go)"]
start["caproni start"]
edit["caproni edit"]
stop["caproni stop"]
end
subgraph Config["Configuration Repo"]
caproni_yaml["caproni.yaml"]
cng_values["cng-values.yaml"]
version_map["version_map.yaml"]
end
end
CNG["CNG Helm Charts<br/>(gitlab-org/charts/gitlab)"]
CLI -->|"manages"| Cluster
CLI -->|"reads"| Config
CLI -->|"deploys"| CNG
CNG -->|"templates"| Cluster
mirrord -.->|"proxies traffic<br/>hijacks DNS"| webservice
puma -.->|"connects via mirrord"| postgres
puma -.->|"connects via mirrord"| redis
puma -.->|"connects via mirrord"| gitaly
style EditMode fill:#e0f2f1
style Cluster fill:#e3f2fd
style CLI fill:#fff3e0
```
### Refs
- [Lucidchart board](https://lucid.app/lucidchart/4167a5d1-1a45-45e4-8796-22dfc7317ceb/edit?invitationId=inv_de6ee160-5a20-4c57-aeb3-d3778a661980&page=0_0#)
## Status
<!-- STATUS NOTE START -->
## Status 2026-04-09
:clock1: **total hours spent this week by all contributors**: 135
:tada: **achievements**:
* Six team members onboarded to Caproni for daily development via demos and user research sessions ([issue](https://gitlab.com/gitlab-org/quality/tooling/team/-/work_items/258))
* [Caproni showcased at Infrastructure All Hands](https://docs.google.com/presentation/d/1sTGlZQ578aYTMSHOaoIC6oXffYubxMPX26mxKw0UVfc/edit?slide=id.g3d3f92969a1_0_433#slide=id.g3d3f92969a1_0_433), raising awareness across the Platform section
* Developers on macOS can now run GitLab Runner locally inside Caproni ([issue](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/issues/10))
* [Fixed port mappings on Linux](https://gitlab.com/gitlab-org/caproni/-/merge_requests/190) so users connect to the load balancer instead of the node IP
* Caproni boots faster on first use thanks to increased Postgres resource limits ([MR](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/67))
* Demo instance reliability improved with automated boot tests ([MR](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/62))
* Running `caproni update-etc-hosts` on a stopped cluster now gives a clear actionable error instead of a confusing failure ([issue](https://gitlab.com/gitlab-org/caproni/-/work_items/59))
* `caproni-demo` now auto-updates itself when a new Caproni release ships, reducing manual maintenance burden ([issue](https://gitlab.com/gitlab-org/caproni/-/work_items/72))
* Groundwork started to let developers build and test AI features (including AI Gateway) locally inside Caproni ([issue](https://gitlab.com/gitlab-org/caproni/-/work_items/77))
* Developers no longer need to manually activate EE license — the [lifecycle management epic](https://gitlab.com/groups/gitlab-org/quality/tooling/-/work_items/129) is fully [closed](https://gitlab.com/gitlab-org/caproni/-/work_items/53)
* Started exploring native data seeding support so developers can test against realistic datasets ([issue](https://gitlab.com/gitlab-org/caproni/-/work_items/78))
* Developers will soon be able to choose a ready-made `caproni.yaml` for their edit-mode use case instead of editing config manually ([MR](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/57))
:issue-blocked: **blockers**:
Not blocking but worth noting:
* Multiple public holidays on April 3 and 6, and Manuel Schönlaub out all week (PTO), reduced team capacity
* Frontend demo for reviewing MRs with Caproni was delayed due to capacity; rescheduled for next week
:arrow_forward: **next**:
* Publish demo showing how to review frontend changes with Caproni to drive organic adoption ([issue](https://gitlab.com/gitlab-org/quality/tooling/team/-/work_items/259))
* Finish [Gitaly edit-mode](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/merge_requests/10)
* Profile GitLab chart startup to find and reduce boot time bottlenecks ([issue](https://gitlab.com/gitlab-com/gl-infra/sandbox/caproni-demo/-/issues/13))
* Ship ready-made `caproni.yaml` config templates for common edit-mode scenarios
* Continue AI Gateway integration so AI feature developers can use Caproni
* Open issues and discussions based on user research findings from this week's demos
_Copied from https://gitlab.com/groups/gitlab-org/-/epics/20677#note_3233700635_
<!-- STATUS NOTE END -->
epic