Edit a project with the builder
EnterpriseChange an existing Arena project with the builder from inside the project editor, and push the builder’s commits so it can run them on real Providers.
Prerequisites
Section titled “Prerequisites”- The builder installed in the workspace. See Install the Arena builder.
- Editor access to the workspace.
- An open project in the editor. See Use the Arena project editor.
Work on the project with the builder
Section titled “Work on the project with the builder”-
In the project editor, select the Builder tab (the others are Files and Try it).
-
Describe the change. The builder opens by asking what you want next, and keeps the brief beside the conversation current. It changes no file until you select Build under the brief. It then edits the project’s files in its sandbox directly.
-
Select Files or Try it when you want to look at the result. The builder and its sandbox stay open while hidden, so the conversation carries on.
The builder’s sandbox mounts your own working clone of the project, arena/workspaces/<project-id>/<user> (<user> is your pseudonymised user id), read-write. Another editor’s builder on the same project mounts their clone. Your dev agent reads the same clone, read-only.
Resolve a file conflict
Section titled “Resolve a file conflict”When the builder finishes a turn, and when you switch back to the dashboard’s window, the editor compares each open file’s content hash with the project on disk.
| Open tab | What happens |
|---|---|
| Unchanged on disk | Nothing |
| Changed on disk, no unsaved edits | The tab reloads with the builder’s version |
| Changed on disk, with unsaved edits | The tab keeps your text and shows This file changed on disk, with Reload, Keep mine and Compare |
| Deleted on disk | The tab keeps its text and shows This file was deleted on disk, with Save again and Close tab |
In the conflict banner:
- Reload discards your unsaved edits and loads what is on disk.
- Keep mine saves your text over the version the banner showed. If the file changed again while the banner was up, the save is refused, the banner updates to the newer version, and you choose again.
- Compare opens a read-only diff, disk on the left and your text on the right.
- Save again recreates a deleted file with the tab’s text. Close tab discards the tab.
The file tree reloads too, so files the builder created or deleted appear or disappear. A save is conditional on the version you opened, so a save you started before the refresh never overwrites a file the builder wrote first.
If the turn changed config.arena.yaml, Try it plans the deploy bindings again and re-applies the dev agent.
Push the builder’s commits
Section titled “Push the builder’s commits”The builder commits its work locally, in logical steps. Each commit is authored as you and carries the trailer Co-authored-by: Omnia builder. The operator records you as the clone’s git identity when it creates your clone of the project, and again whenever you open the Source control tab. The builder never pushes, and a real-provider run builds only from a pushed commit.
- Ask the builder to run the project on real Providers, or to push.
- The builder shows a Push your changes card in the conversation, with how many commits go to which branch. A hosted project syncs
main. An external project pushes your branch with your own Git account (link it on the Connections page if the card asks). - Select Push to main (hosted) or Push
<branch>(external). To push later, select Not now and push from the Source control tab at any time. The builder does not run until you push.
If the builder starts a run without asking first, the run is refused and the builder panel shows The builder needs your changes pushed before it can run, with the same push. Once you push there, the panel tells the builder to start the run.
Verify
Section titled “Verify”The card shows what was pushed, and the builder starts the run, then reports its result in the conversation. The run runs exactly the commit your clone has checked out. The builder can also check the clone as it stands, uncommitted changes included, so it can fix problems before it commits.
Troubleshooting
Section titled “Troubleshooting”arena_start_run refuses with a 409. The first three causes carry a code.
409 with code not_pushed
Section titled “409 with code not_pushed”The builder’s commits are not pushed. Push them from the panel the builder shows, or from the Source control tab.
409 with code uncommitted
Section titled “409 with code uncommitted”The clone has uncommitted changes, or no commits. The builder commits them, or you discard them on the Source control tab.
409 with code diverged
Section titled “409 with code diverged”Your branch and the repository have both moved, or HEAD is not on a branch. Reconcile the branch on the Source control tab, then ask the builder to run again.
409 “the workspace is busy”
Section titled “409 “the workspace is busy””git in the sandbox, or another source-control request, holds the clone’s index.lock. Try again once it finishes.
409 “a run of this commit is already in progress”
Section titled “409 “a run of this commit is already in progress””The builder starts one real-provider run of a commit at a time. The message names the run in flight, which runs the same pushed commit, and the scenarios and providers it runs. When that is the selection the builder asked for, it polls the run with arena_get_run; otherwise it waits for the run to finish and then starts its own. Runs of other commits, such as another person’s work on the same project, do not block it, so a project can have as many real-provider runs going at once as people who have pushed different commits.
Sync is refused with “the push contains a commit authored by someone else”
Section titled “Sync is refused with “the push contains a commit authored by someone else””A hosted push refuses any commit authored by someone other than the person pushing, whether or not it carries the builder’s trailer. Reset that commit’s author, or discard the commit, and sync again.