Skip to main content
Connect a GitLab project to an app so Meridian can build and deploy from your source, and so a push can ship a release. It works like GitHub, with the differences described here.

What you need

  • A GitLab account that has the Maintainer role on the project you want to connect. Meridian needs it to create a service account and a webhook in the project.
  • The Integrations: Edit permission in your Meridian organization.

Connecting a project

  1. Open your app’s Settings → Integrations and choose GitLab on the repository card.
  2. Sign in to GitLab and approve access to your account.
  3. Choose the GitLab account (top-level group or personal namespace) to connect.
  4. Pick a project. Meridian lists only projects where you are Maintainer, and you can search by name.
  5. Confirm.
You can also create a brand-new Meridian app directly from a GitLab project. Finish the GitLab step in the same browser, logged in to Meridian as the user who started the connection. Otherwise nothing is connected, and Meridian asks you to log in and connect again. Once an account is connected, every teammate with the permission can connect more of its projects without signing in to GitLab themselves.

What Meridian creates in your project

GitLab has no equivalent of a GitHub App, so Meridian creates its own identity inside the project:
  • A service account named “Meridian”, added to the project with the Reporter role. Reporter can read code but cannot push. Every clone, branch list and scan runs as this account, so your own login is never used to deploy.
  • A read-only access token for that account. Meridian renews it yearly by itself.
  • A webhook that tells Meridian about pushes and merge requests. Meridian verifies every delivery’s signature.
This keeps access tied to the project, not to the person who connected it. If that person leaves the group, connected apps keep deploying.

Deploying from GitLab

With a project connected:
  • Push to deploy: a push to the connected branch triggers a deployment. Tags and deleted branches are ignored.
  • Merge request previews: a merge request gets its own preview deployment at its head commit, torn down when the merge request is closed or merged, or after seven days without a push. An app keeps at most two live previews.
  • Manual deploys: pick any commit and deploy it from the dashboard.
A preview only builds when the merge request comes from a branch of the connected project itself, and its author has the Developer role or higher on that project. Merge requests from forks, and from anyone below Developer, never build, because a preview runs the merge request’s code. Previews cannot reach your app’s secrets, as on GitHub. Meridian does not comment on merge requests. To find a preview’s URL, status and expiry, use the previews_list tool of the Meridian MCP server. Several apps of your organization can connect the same project. Each one applies its own branch, target and previews. Deployment access rules are the same as on GitHub: see Deployment.

One Meridian organization per GitLab account

A GitLab account belongs to the first Meridian organization that connects it. Connecting it from another organization fails with “This GitLab account is already connected to another organization”. Reconnecting from the owning organization refreshes the sign-in and never transfers ownership. The account stays connected until someone with Integrations: Edit disconnects it in Meridian. If the person who connected leaves your Meridian organization, their GitLab sign-in is deleted and the account shows Sign in to GitLab again before you can connect more projects. Apps already connected keep deploying.

Reconnect GitLab

Meridian checks every connected project every 10 minutes. If it finds that a push was missed, for example because the webhook was removed or disabled, it still deploys within about 15 minutes. After three missed pushes in a row the app shows Reconnect GitLab. Choose it, sign in to GitLab, and Meridian recreates the webhook, re-adds the Meridian account if it was removed and issues a new token if needed. If the project is deleted or the Meridian account loses access, the app shows the same “repository disconnected” state as on GitHub. Meridian notices this within about 20 minutes, a little slower than GitHub, and sooner while you have the app open. The GitLab card on Integrations then reads Disconnected and offers Reconnect GitLab, which re-adds the Meridian account and repairs the webhook and token the same way. If the project itself is gone, choose Disconnect and connect another project.

Disconnecting

Disconnect on the GitLab card stops push and merge request deploys. Running revisions are unaffected until the next deploy. When the last app on a project is disconnected, Meridian revokes its token. If your sign-in still works and you are Maintainer, it also deletes the webhook and the “Meridian” service account. Otherwise they stay behind, inert, and you can remove “Meridian” from the project’s Members page in GitLab (Open in GitLab links there).

Troubleshooting

Last modified on November 13, 2026