GitLab

Connect your GitLab account so the agent can clone and push repositories on gitlab.com or a self-managed GitLab instance, run glab, and follow merge requests, issues, and CI from a thread. This page explains how to connect, how a workspace sets up a self-managed instance, which network connections Amp makes, and how Push Updates and subscriptions work.

Connect GitLab

Open Settings → Integrations & MCP and find the GitLab card.

  • gitlab.com. Click Connect GitLab and sign in to gitlab.com. Amp connects through its own OAuth application.
  • A self-managed instance. A workspace admin must first register the instance and set up an OAuth application for it. See Self-Managed Instances. The card then lists the instance, and you click Connect GitLab on its row. The button at the top of the card then reads Connect gitlab.com. Until the workspace has an OAuth application for the instance, its row says that an admin must set one up, and you cannot connect it.

GitLab asks you to authorize Amp for two scopes:

  • api to read your account, merge requests, issues, and pipelines, and to install Push Updates.
  • write_repository to clone and push over HTTPS. The api scope does not cover Git.

If GitLab grants fewer scopes, Amp does not save the connection.

You have one connection per instance. Each appears as a row such as @alice on gitlab.com:

  • Disconnect deletes the tokens Amp holds for that instance and revokes Amp’s grant on GitLab.
  • Reconnect appears when the connection stopped working, with the reason, for example when GitLab revoked or expired it. Click it to sign in again.

When you can install Push Updates in one of your workspaces and have not yet, a Set Up Push Updates row links to that workspace’s GitLab settings.

What Amp Uses the Connection For

  • Cloning and pushing in orbs. Before an orb starts, Amp checks that your connection can read the project’s repository and tells you what to fix if it cannot. Git in the orb then clones, fetches, and pushes as you. See How Orbs Authenticate to GitLab.
  • glab in orbs. The glab CLI is preinstalled and signed in with your connection, so glab mr create and glab ci view work without glab auth login.
  • Creating projects. The New Project dialog lists the GitLab projects you are a member of on each instance you connected. See Projects.
  • Merge request, issue, and pipeline details. The agent reads merge requests, issues, and pipelines through Amp with your connection. These reads never hand your token to the orb.
  • Subscriptions. A thread can follow merge requests, issues, and CI. See Subscriptions.

Branch protection and project permissions apply exactly as if you had pushed from your own machine.

How Orbs Authenticate to GitLab

Whenever the agent runs a Git command that talks to a GitLab instance, Git asks Amp’s credential helper for a token. The helper covers gitlab.com and every instance you connected.

glab asks the same credential helper for each request, and only sends a host’s token to that host. If GITLAB_TOKEN, GITLAB_ACCESS_TOKEN, OAUTH_TOKEN, or GLAB_CONFIG_DIR is set in the orb, for example as a project secret, glab uses it instead of your connection. Remove it from the project’s Secrets & Env Vars to use your connection. glab uses HTTPS for Git, since the orb has no SSH keys for GitLab.

Threads that run on a runner or in a local CLI session use the Git configuration and credentials of that machine.

Self-Managed Instances

A workspace registers each self-managed GitLab instance its members use. Registration lets members connect through the workspace’s OAuth application, lets the workspace install Push Updates, and lets threads subscribe to the instance’s projects.

Register the Instance

A workspace admin opens Workspace Settings → Integrations & MCP, opens GitLab, and clicks Add GitLab Instance. Enter the instance’s HTTPS URL. Before saving, Amp checks that the URL answers like a GitLab instance, so the instance must accept requests from Amp’s servers. See Network Requirements. Amp does not support instances served under a subpath, such as https://example.com/gitlab.

Set Up the OAuth Application

Members connect a self-managed instance through the workspace’s OAuth application, so an admin must set one up before anyone can connect. On the instance’s OAuth Application row, click Set Up OAuth and follow the steps:

  1. In GitLab, create the application in one of these places:
    • Instance application. As a GitLab administrator, open Admin area → Applications and select New application.
    • Group application. As an Owner of a group, open the group’s Settings → Applications.
  2. Set Redirect URI to https://ampcode.com/auth/gitlab/callback.
  3. Keep Confidential selected, and select the api and write_repository scopes.
  4. Save the application, then paste the Application ID and Secret GitLab shows into Amp and click Save.

For an instance application, you can also select GitLab’s Trusted option. GitLab then skips its authorization screen when members connect. GitLab offers this option only for applications created in the Admin area.

Members then click Connect GitLab on the instance’s row in their own Settings → Integrations & MCP. Before sending them to GitLab, Amp checks that its servers can reach the instance, so a blocked instance shows an error before anyone signs in.

To change the application, click Replace. Remove deletes it from Amp; members who connected through it must reconnect after an admin sets up another application.

When Members Need to Reconnect

An OAuth connection belongs to the application that issued it. A member’s connection stops working, and their GitLab card asks them to reconnect, when:

  • A workspace admin replaces the OAuth application.
  • A workspace admin removes the OAuth application.
  • A workspace admin removes the instance, which also deletes its application.
  • The member leaves the workspace.
  • GitLab revokes or expires the connection.

The member clicks Reconnect on their GitLab card. If the workspace no longer has an application, an admin must set one up first.

Network Requirements

Amp connects to your GitLab instance from two places: Amp’s servers and the orbs. Your instance also connects to Amp to deliver Push Updates.

Amp’s Servers to Your GitLab

Amp’s servers call your instance’s API over HTTPS. The instance must be reachable over the public internet; Amp’s servers never connect to private network addresses. If the instance accepts only known IP addresses, allow Amp’s server IP addresses. All of these requests come from those addresses:

  • Checking that an instance answers like GitLab when an admin registers it, saves an OAuth application, or a member starts connecting.
  • Reading the account of a new OAuth connection.
  • Exchanging the OAuth authorization code for tokens, refreshing OAuth tokens before they expire, and revoking them on disconnect.
  • Listing your projects in the New Project dialog, and checking repository access before an orb starts.
  • Reading merge requests, issues, and pipelines for the agent.
  • Listing your groups and projects for Push Updates, installing or repairing webhooks, and sending GitLab’s test push.
  • Checking the project when a thread subscribes, checking the subscriber can still read it before each delivery, and polling the commit’s pipelines for CI subscriptions.

Your GitLab to Amp

For Push Updates, your instance sends webhooks to https://ampcode.com. If your network filters outbound traffic from the instance, allow HTTPS to ampcode.com.

GitLab’s own outbound request settings block only local network addresses by default, so they need no change. If an administrator selected Block all requests, except for IP addresses, IP ranges, and domain names defined in the allowlist under Admin area → Settings → Network → Outbound requests, add ampcode.com to Local IP addresses and domain names that hooks and integrations can access. See GitLab’s Filtering outbound requests.

Orbs to Your GitLab

git clone, git push, and glab run inside the orb, so they connect from the orb host’s addresses, not from Amp’s server IP addresses. Those addresses change. To let an Amp-hosted orb reach an instance that allows only known addresses, connect the orb to your network with Tailscale, or run orbs in your own network with self-hosted orbs.

When an Instance Blocks Amp

When Amp’s servers cannot reach an instance, the error names its host and what to fix:

  • ”host refused requests from Amp’s servers.” Something in front of GitLab, such as an IP allowlist, answered instead of GitLab. The message links to Amp’s server IP addresses.
  • “Amp’s servers could not connect to host.” The connection failed or timed out.
  • ”host is not on the public internet.” The host name resolves to a private network address.

These errors appear when you connect GitLab, when an admin registers an instance or saves its OAuth application, when you install Push Updates, and when a thread subscribes.

Push Updates

Push Updates are GitLab webhooks that tell Amp about pushes, merge requests, issues, comments, and CI results. They deliver events to subscriptions, and pushes keep the workspace’s prewarmed orbs up to date. Set them up in Workspace Settings → Integrations & MCP under GitLab, in the Push Updates for gitlab.com panel or the panel of a registered instance.

Any workspace member can install Push Updates. Amp installs the webhooks with your own GitLab connection, so connect GitLab on that instance first. Only workspace admins can remove them.

Install Push Updates

Not Installed lists the top-level groups you own that have no Amp webhook yet, and the workspace’s repositories outside those groups that no webhook covers and that you maintain. Choose All groups and repositories or Only select groups and repositories, then click Install. With all groups, projects added to those groups later are covered too, except in groups on GitLab Free.

GitLab decides which webhooks you can add:

  • A group webhook covers every project in the group and its subgroups. It needs the Owner role on the group and GitLab Premium or Ultimate.
  • A project webhook covers one project. It needs the Maintainer role on the project.

On GitLab Free, or GitLab Community Edition, groups have no webhooks. When GitLab refuses a group webhook, Amp adds project webhooks to the projects in that group that you maintain: the workspace’s repositories first, then up to 50 others. Repositories where you are not a Maintainer appear under Can’t Install.

Amp’s webhook is named Amp. It fires on pushes, merge requests, issues, confidential issues, comments, confidential comments, and pipelines. After installing it, Amp asks GitLab to send a test push. The panel then shows Receiving and when the last event arrived.

Under Details, Repair gives a webhook a new signing secret. Remove stops Amp from using it; also delete the webhook in GitLab under Settings → Webhooks.

The one-button install signs webhooks with a GitLab signing token, which GitLab added in version 19.0. On an older instance, set up the webhook manually.

Set Up a Webhook Manually

Click Set up a webhook manually, choose GitLab group or Single project, enter its path, and click Continue. Amp shows the steps:

  1. Open the group’s or project’s webhooks page in GitLab and select Add new webhook.
  2. Paste the URL Amp shows. It starts with https://ampcode.com/api/webhooks/gitlab/.
  3. Paste the secret token Amp shows.
  4. Under Trigger, select Push events, Comments, Confidential comments, Issues events, Confidential issues events, Merge request events, Job events, and Pipeline events. Keep SSL verification on.
  5. Select Add webhook, then Test → Push events. Amp shows Receiving as soon as the test arrives.

Click Show Setup on the webhook’s row to see the URL and secret token again.

How Amp Verifies Deliveries

Amp accepts a delivery only when it comes from the instance the webhook belongs to and carries that webhook’s secret:

  • Webhooks Amp installs use a GitLab signing token. Amp checks the HMAC-SHA256 signature over the payload and rejects deliveries signed more than 10 minutes earlier or later.
  • Webhooks you set up manually send their secret token, which Amp compares with the one it issued.

Amp answers every verified delivery with success, even one it could not apply, so GitLab does not disable the webhook.

Subscriptions

A thread can subscribe to events from one GitLab project on gitlab.com or a registered instance, so Amp continues the thread when something happens instead of polling. Ask in the thread that should receive the events:

Watch MR !42 in https://gitlab.example.com/acme/widget for comments and reviews. Address feedback in this thread and ask me before pushing.
Follow CI for the commit we just pushed to https://gitlab.com/acme/widget and tell me when the pipelines finish. Report failures, but do not retry jobs.
  • Merge request comments cover comments on one merge request, plus its merge, close, reopen, approval, changes requested, and target branch change events.
  • Issue comments cover comments on one issue, plus its close and reopen events.
  • CI covers the pipelines for one commit. Amp reports a failed pipeline as soon as it fails, then sends one final message when every pipeline has finished, or when none ran. Amp also checks the commit’s pipelines itself, in case a webhook is missed. CI subscriptions end 24 hours after creation.

A subscription needs:

  • Your own GitLab connection on the project’s instance.
  • Push Updates that cover the project, installed in the thread’s workspace.
  • A thread in a workspace. GitLab webhooks belong to a workspace, so personal threads cannot subscribe.

Events about confidential issues and internal comments reach the thread only when you have at least the Reporter role on the project.

After the agent opens a merge request or issue, it can subscribe as an automatic follow-up. That subscription pauses while the merge request or issue is closed and skips events you caused, unless your comment mentions @ampagent.

To pause, resume, or delete a subscription, ask the agent in the thread. Settings → Integrations & MCP lists your subscriptions under GitLab → Event Subscriptions.

Create an Orb Spawner

An orb spawner starts a new thread and orb for each newly opened merge request or issue in one GitLab project. The new thread reads the merge request or issue and summarizes it. Open the thread to continue the work.

Ask Amp or Puck to set up a spawner. Choose a project connected to the GitLab repository and tell Amp which agent mode to use. Use a workspace project, or one of your personal projects:

For each new merge request in https://gitlab.example.com/acme/widget, start a new orb in our Widget project using Medium mode.

You can filter new merge requests or issues by a label present when they open. Adding the label later does not start an orb. You can also give the new orbs instructions to follow, such as “Review the merge request and post a summary comment.” Comments and pipelines cannot spawn new orbs.

You can also create a spawner in Settings → Integrations & MCP under GitLab → Event Subscriptions with New Subscription. The same table lets you edit, pause, or delete a spawner, and lists the orbs it started under Spawned Orbs.

Amp automatically subscribes each spawned thread to comments on its merge request or issue, and to the other events a merge request or issue subscription covers. You can archive the thread where you set up the spawner without stopping the spawner. Pause or delete the spawner when you no longer want new orbs.

A spawner works like a subscription:

  • It needs your GitLab connection on the project’s instance and Push Updates that cover the project.
  • A spawned orb acts on GitLab as you. Comments and changes it makes do not reach its own thread again, so the orb does not reply to itself.
  • Confidential issues start an orb only when you have at least the Reporter role on the project.

Run a Spawner as a Service Account

Workspace admins can create a spawner that belongs to the workspace and starts each orb as a service account, so the whole workspace can read the orbs it starts. Amp asks an admin to confirm before it creates one.

First give the service account a GitLab connection. In Workspace Settings → Service Accounts, click Connect on the account’s row and choose GitLab Account for the instance. Sign in to GitLab as the user the service account should act as, for example in a private window, and approve Amp. GitLab service accounts and project or group access tokens cannot sign in, so use a regular GitLab user. On paid GitLab plans, that user takes a seat.

Then create the spawner under Event Subscriptions → GitLab on the same settings page, or ask Amp or Puck:

For each new issue labeled triage in https://gitlab.example.com/acme/widget, start a new orb as our Triage Bot service account in the Widget project using Low mode.

The project must belong to the workspace. Each spawned thread belongs to the service account and is shared with the workspace, and the admin who created the spawner follows each one. Only workspace admins can edit, pause, or delete these spawners.