Skip to content

Watch GitLab work ​

Connect GitLab when an agent should respond in issues and merge requests. GitLab tells AgentX about new activity through a webhook: a message GitLab sends to an address you give it every time something happens in a project. An agent replies when a comment @-mentions it.

Start with a test project. Give AgentX the smallest access that lets it do the job.

1. Create a GitLab token ​

  1. Browser, in GitLab: open your user settings and create a personal access token with the api scope. Use a dedicated GitLab user for the agent if you can.
  2. Copy the token. Treat it like a password.
  3. On the AgentX machine, open the .env file next to agentx.json.
  4. Add a line with the token, then save the file:
    sh
    GITLAB_TOKEN=paste-the-token-here

2. Connect GitLab in AgentX ​

  1. Browser: open the Hub and select Settings.
  2. Select Channels.
  3. Select GitLab at the top.
  4. Under Host, enter your GitLab address, such as https://gitlab.com or your own GitLab server.
  5. Under Admin token (api scope), as an environment variable name, enter GITLAB_TOKEN (the name of the line you added, not the token itself).
  6. Leave Webhook listen port at 18810 unless that port is taken.
  7. Select Connect.

Settings › Channels › GitLab, with Host, the admin token variable set to GITLAB_TOKEN, and Webhook listen port

GitLab sends events to that port on the AgentX machine, not to the dashboard. GitLab must be able to reach it, for example over a private network (see Tailscale setup). Don't open it to the whole internet without a secret (step 3.6 below).

By default, each agent answers to the GitLab username that matches its agent ID. To map other usernames or give each agent its own token, edit channels.gitlab.agentMappings in Settings › Advanced.

If your team names its GitLab bot accounts with a common prefix, for example team-reviewer for the agent reviewer, set it once instead of mapping every agent: add "agentUsernamePrefixes": ["team-"] under channels.gitlab. Each agent then also answers to @team-<agent-id>.

3. Add the webhook in GitLab ​

  1. Browser, in GitLab: open the test project.
  2. Open Settings › Webhooks.
  3. Select Add new webhook.
  4. Under URL, enter the AgentX machine's address and the webhook port, for example http://agentx.example.internal:18810/.
  5. Tick Comments, Issues events and Merge request events. Add Pipeline events if the agent should see pipelines.
  6. Optional: under Secret token, enter a long random value. Then, in AgentX, add "webhookSecret": "<the same value>" to channels.gitlab in Settings › Advanced, and select Save. AgentX then refuses events without it.
  7. Select Add webhook.

The Webhooks form in a GitLab project: URL, Secret token and the Trigger checkboxes

4. Optional: show the state of each request in the issue ​

Without this, an issue is silent between the request and the agent's answer. With it, AgentX keeps one comment per request up to date: queued, working, waiting, done, failed, timed out, or cut off by a restart.

  1. Terminal: open the folder that holds agentx.json.
  2. Run agentx request-status gitlab on.
  3. Run agentx request-status and check that gitlab shows on.

To turn it off again, run agentx request-status gitlab off. Details: requestStatus.

Check it worked ​

  1. Browser, in GitLab: on the webhook, select Test › Issues events. GitLab shows HTTP 200.
  2. Browser, in GitLab: in a test issue, add a comment that @-mentions the agent's GitLab username.
  3. Within a minute or two, the agent replies in the issue.
  4. Browser, in AgentX: open Activity. The request appears under the agent.
  5. If request status is on: a comment that starts with Request status: appears in the issue when the agent starts, and the same comment changes to Done when it ends. There is still only one such comment.
  6. Terminal: run agentx daemon status. No red GitLab: line appears. A red line means GitLab refused one of your tokens (see below).

If something is wrong ​

  • GitLab shows a connection error: GitLab can't reach the AgentX machine on port 18810. Check the address, the port and any firewall.
  • GitLab shows 401: the Secret token in GitLab doesn't match webhookSecret in AgentX.
  • GitLab shows 200 but nothing happens: the comment has no @-mention, or it mentions a username no agent answers to. Check agentMappings.
  • The agent runs but never posts a reply: the token in .env is missing, revoked, or belongs to a user without access to the project. Check agentx daemon logs for GitLab API error.
  • agentx daemon status shows a red GitLab: line, such as "GitLab rejected the global token": GitLab answered 401 (not signed in) when AgentX checked or used that token, for example because it was revoked. Every post made with it fails until you replace it. The agent is told: its send returns an error with GitLab's message instead of "Message sent". To fix it:
    1. Browser, in GitLab: create a new token with the api scope, as in step 1.
    2. Terminal: put the new token in .env in place of the old one.
    3. Terminal: run agentx daemon restart.
  • A send says "Posted with the shared global gitlab token": the post went through, but under the shared bot user, because that agent has no GitLab token of its own. To post as the agent, give it a token in channels.gitlab.agentMappings. An agent's own tools name it on GitLab without being told. A post with no agent behind it, such as a direct call to /send, also uses the shared bot and leaves a [gitlab/identity] line in agentx daemon logs that says "no agent id on the request".
  • The status comment stays on "Working" after the agent answered: the edit was refused. Check agentx daemon logs for GitLab edit error. The token must belong to the same GitLab user that wrote the comment.
  • Still stuck: follow It's not answering.

Released under the MIT License.