> ## Documentation Index
> Fetch the complete documentation index at: https://help.the-meridian.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> These are the public docs of Meridian for Shopify apps: hosting, billing (Plan Builder and the @the-meridian/sdk package), CRM, emails and automations for Shopify app developers.
> Start with these pages: Meridian MCP (https://help.the-meridian.ai/mcp-server.md) to connect a coding agent, AI coding agents (https://help.the-meridian.ai/ai-agents.md) for the agent skill, SDK quickstart (https://help.the-meridian.ai/sdk-quickstart.md), Running your app with the CLI (https://help.the-meridian.ai/cli-dev.md), Deployment (https://help.the-meridian.ai/deployment.md), and Errors (https://help.the-meridian.ai/errors.md) to look up an error code or message.
> Fetch one page at a time as Markdown (the page URL followed by .md), using the index in https://help.the-meridian.ai/llms.txt. llms-full.txt holds every page in one file of about 900 KB, so avoid loading it whole.
> With Meridian MCP connected, search these docs with docs_search and docs_get, and read live facts (feature and event keys, plan ids, environments, deployments, logs) from the MCP tools instead of guessing them.

# Connect GitLab

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](https://help.the-meridian.ai/github.md), 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](https://help.the-meridian.ai/customer-permissions.md) 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](https://help.the-meridian.ai/deployment.md). 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](https://help.the-meridian.ai/github.md).

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](https://help.the-meridian.ai/mcp-server.md).

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](https://help.the-meridian.ai/deployment.md).

## 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

| Message | What it means and what to do |
| - | - |
| You need the Maintainer role on this project to connect it. | Ask a project Owner or Maintainer to raise your role, or ask one of them to connect it. |
| This GitLab group has reached its limit of service accounts. | GitLab Free allows 100 service accounts per top-level group. Delete unused ones in the group, then try again. |
| Verify your identity in GitLab, then try again. | Projects in a GitLab trial namespace need identity verification first. |
| Your GitLab group does not allow access tokens. | A group policy blocks token creation. Ask a group Owner to allow it. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.