Run Your First Ticket-to-Code Job

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

• Cloud Hosted is selected, or the Self Hosted worker is enrolled
• the AI provider path is ready
• integrations are connected
• a repository is enabled for work
• intake labels and states are configured

Use the Right Run Surfaces

Use https://controller.mergeloom.ai for job creation, intake status, Cloud Hosted audit, controller audit, and PR/MR coordination. For Self Hosted, use the local worker UI at http://127.0.0.1:8010/ for worker/provider readiness and local execution detail, Ticket Audit, and Code Audit.

Self Hosted setup: confirm the worker enrollment values are available before starting the first self-hosted 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 repositories, 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 repository 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 smoke job only to validate setup before enabling scheduled intake. It is not a retry or recovery action.

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

The manual form is best for simple repository-workflow tests. Required fields include:

• repository workflow
• ticket_key
• title

Use a real ticket for detailed instructions, comments, routing directives, or multi-repository work.

Watch the Run

Use these surfaces:

• MergeLoom customer controller
• worker UI for Self Hosted

Useful Docker logs for Self Hosted:

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 started processing the job.

Customer controller: use the job audit view to see what happened during the run. For Self Hosted, 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. The controller detects an eligible ticket or issue.
2. The controller creates a job record.
3. The selected execution path starts the job.
4. MergeLoom prepares the repository workspace.
5. Clarity Agent checks whether the ticket is ready enough to run.
6. Context Engine and Investigation Agent prepare the implementation brief.
7. Implementation Agent writes the change.
8. Validation commands run.
9. Repair Agent and Review Agent run when configured.
10. Diff Guard checks the size and shape of the change.
11. MergeLoom pushes a branch.
12. The controller creates or updates the PR or MR.
13. Work tracker receives progress comments and workflow state changes.
14. 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 one of the accepted prefixes:

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

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

   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.

Use Retry publish only when the job already produced branch artifacts but failed while creating or updating the PR or MR. Retry publish does not rerun AI coding or validation; it reattempts the publish step from stored artifacts.