Skip to content

Run your first job

With the webhook registered, an agent and trigger configured, and the workspace subscribed (Settings → Billing → Subscribe, Owner only: pick Shared or Dedicated and the number of mates; a billing profile must be saved first), you are ready to run Mate for the first time.

The simplest trigger to test is an issue assignment (on: issue with assigned: true, part of the Teammate template). In GitLab:

  1. Open any issue in the project where you registered the webhook.
  2. In the Assignees field on the right sidebar, assign the issue to the managed account.

GitLab fires a webhook event to Mate. Within a few seconds, a status note from the account appears on the issue (queued, then working) and a new job appears in the console.

If the project is empty (no commits), Mate first commits a README.md to the default branch (main if none is configured) so there is something to clone and merge requests have a target.

Navigate to Jobs in the workspace sidebar. The table (status, agent, triggered by, project, event, started, duration) refreshes every few seconds and can be filtered by status, agent, account and project.

The job passes through these statuses:

Status Meaning
PENDING Accepted, waiting for a free mate (concurrent slot)
DISPATCHING Container is being started
STARTING Container is booting
RUNNING Agent is actively executing
FINISHING Agent finished; container is shutting down
DONE Job completed normally
CANCELED Stopped by user or timeout
ERRORED Unexpected failure

Once a job has finished, its chip shows the outcome instead of the status: SUCCESS, FAILURE, CANCELED or TIMEOUT.

Click any row to open the Job page.

The job page shows a summary (status or outcome, who triggered it, managed account, project, issue or MR, agent, trigger, start and finish time, duration, tool call count, estimated cost) and a Log that streams in as the job runs, oldest first:

  • Agent text — what the agent says as it works.
  • Thinking — the agent’s reasoning, collapsed.
  • Tool calls — each tool the agent called, with duration; expand one for its arguments, result or error.
  • Container build — the build phases, if Mate had to build an image from the repository’s devcontainer.
  • Status changes — a divider with the new status and time.
  • Final status — the outcome, exit code and the agent’s summary.

While the job is running the log is labelled LIVE. Use Pause to stop the live feed temporarily and Resume to continue. The cost is an estimate at list price computed by the agent CLI, not what your provider bills.

To cancel an in-flight job, click Cancel job on the job page (Managers and Owners). Cancellation is accepted immediately; the job moves to FINISHING and then CANCELED.

The agent acts as the managed account. Depending on the permissions you granted, it replies with comments, pushes branches, opens merge requests, and updates issues; the Teammate template’s prompt makes it finish with one short comment saying what it did and what is left. Mate also edits a single status note on the issue or MR as the job progresses (queued, working, done, or stopped). The agent can also create issues and assign or @-mention its own account to hand work to a follow-up job; those appear as further rows in Jobs.

Check the issue or MR in GitLab that triggered the job to see the result.

  • No job row after 30 seconds: check that the webhook was saved correctly in GitLab (Settings → Webhooks → Recent deliveries). A 401 response means the secret is wrong. A network error means GitLab could not reach ingest.mate.engineer. A 200 with no job means no trigger matched the event, the user who caused it is not in allowed_users (if you set that), or the workspace has no subscription: in that case Mate posts a note on the issue or MR saying so.
  • Job appears but stays ERRORED: open the detail page and check the log events for the error message. Common causes are a missing or expired LLM key, an LLM key that is incompatible with the agent’s backend (Mate posts the reason on the GitLab note), a managed account without access to the project, or a config validation error.
  • Job completes but the bot did nothing in GitLab: the agent ran but determined no action was needed, or it lacks the necessary permissions or GitLab access. Check the tool call events and review the permissions list in your agent config.

You have completed the walkthrough. Mate is set up and running jobs. From here you can:

  • Refine the agent’s system_prompt to match your project conventions.
  • Add triggers for other events (review requests, label-filtered MR events, other pipeline statuses).
  • Expand permissions once you are confident in the agent’s behaviour.
  • Register the webhook on additional projects — each project sends events to the same workspace’s webhook URL.