Run your first ticket-to-code job

Run your first ticket-to-code job only after:

• the worker is enrolled
• an AI provider is ready
• integrations are connected
• a repository is enabled for work
• intake labels and states are configured

Use both UIs during the first run

Use https://controller.mergeloom.ai for job creation, intake status, audit state, and PR/MR coordination. Use the local worker UI at http://127.0.0.1:8010/ for worker/provider readiness and local execution detail.

Customer controller: confirm the worker enrollment values are available before starting the first job.

Link the ticket to a repository

Before you run the first job, make sure MergeLoom knows which repository the ticket should change.

Open Repository catalog in the customer controller at https://controller.mergeloom.ai. Each enabled repository has an alias. That alias becomes the routing label you add to the ticket.

Example:

Repository alias	Ticket label
server	repo-server
web	repo-web
api	repo-api

If your workspace has more than one enabled work repository, add the matching repo-<alias> label to the ticket, issue, work item, or board item. For example, if the repository alias is web, add:

repo-web

If the alias is wrong or the label is missing, MergeLoom cannot safely decide where to make the change. It will leave the ticket in place, record the routing problem in the controller activity log, and wait for you to fix the label or the repository catalog entry.

Customer controller: use the repository alias from Repository catalog as the matching ticket label, for example repo-web.

Path A: Real ticket or issue

Use a real ticket when you want to test the normal workflow.

1. Create a small ticket or issue.

2. Add the managed intake label:

   mergeloom

3. Add a repo routing label if needed:

   repo-server

4. Confirm the routing label matches the repository alias in Repository catalog.

5. Put the ticket in the ready state.

6. In Global workflow settings, turn Scheduled intake on.

7. Wait for scheduler intake.

Work tracker: a good first live test has the managed intake label and the repository routing label on a small, easy-to-review ticket.

Good first ticket:

Update README.md with a short local health-check section.
Keep the change under 30 lines.
Run the repository validation command before opening the PR.

Path B: Manual smoke job

Use a manual job when you want to validate the worker loop before trusting live intake.

In the MergeLoom controller at https://controller.mergeloom.ai, use Create Manual Job.

Required fields currently include:

• repository workflow
• ticket_key
• title

Current limitation:

• the manual job form does not yet expose a description field, so advanced multi-repo or detailed ticket instructions are better tested from a real ticket or issue

Watch the run

Use these surfaces:

• MergeLoom customer controller
• admin UI
• worker UI

Useful Docker logs:

docker compose logs -f
docker compose logs -f worker-gateway
docker compose logs -f worker-executor-1

Local worker UI: watch the worker run list when you need to confirm that an executor leased the job and started processing it.

Customer controller: use the job audit view to see what happened during the run. Use the local worker UI when you need worker-local provider and trace details.

Expected successful end state

For a configured issue-to-review path:

1. Control plane detects an eligible ticket or issue.
2. Control plane creates a job envelope.
3. Worker executor leases the job.
4. Worker prepares the repository workspace.
5. AI provider runs inside the worker execution path.
6. Validation commands run.
7. Worker pushes a branch.
8. Control plane creates or updates the PR or MR.
9. Work tracker receives progress comments and workflow state changes.
10. Slack or Teams notifications fire if configured.

Code host: a successful run ends with a branch and PR or MR that your team can review through its normal code review workflow.

If validation fails

Depending on your settings, MergeLoom can:

• retry with a bounded repair loop
• mark the job blocked
• leave a clear failure reason
• preserve trace information for review

Do not treat a failed first run as wasted. The failure usually tells you which setup area needs attention:

• provider auth
• repository permissions
• missing dependency
• wrong validation command
• ambiguous ticket
• wrong workflow state mapping

Continue a blocked or reviewed ticket

To ask MergeLoom for another pass:

1. Comment on the ticket with:

   MergeLoom - please update the PR to also cover ...

2. Move the ticket back to the configured ready state.

3. Wait for intake.

MergeLoom should pick up the new context and update the existing review branch when possible.