---
title: How can I use GitLab Pipelines with Vercel?
description: Learn how to use GitLab Pipelines to deploy to Vercel including support for self-managed GitLab.
url: /kb/guide/how-can-i-use-gitlab-pipelines-with-vercel
canonical_url: "https://vercel.com/kb/guide/how-can-i-use-gitlab-pipelines-with-vercel"
last_updated: 2026-07-16
authors: Lee Robinson, Anna Z.
related:
  - /docs/deployments/git/vercel-for-gitlab
  - /docs/concepts/deployments/preview-deployments
  - /docs/concepts/projects/custom-domains
  - /docs/concepts/git/vercel-for-gitlab
  - /docs/build-output-api/v3
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

[​Vercel for GitLab](https://vercel.com/docs/deployments/git/vercel-for-gitlab) automatically deploys your GitLab projects with [Vercel](https://vercel.com/), providing [Preview Deployment URLs](https://vercel.com/docs/concepts/deployments/preview-deployments#preview-urls), and automatic [Custom Domain](https://vercel.com/docs/concepts/projects/custom-domains) updates.

For advanced usecase, you can use Vercel with GitLab as your CI/CD provider to generate Preview Deployments for every `git` push and deploy to Production when code is merged into the `main` branch.

This approach is useful for developers who want full control over their CI/CD pipeline, as well as GitLab Self-Managed users, who can’t leverage Vercel’s built-in [git integration](https://vercel.com/docs/concepts/git/vercel-for-gitlab).

You can [view the completed example here](https://github.com/vercel/examples/tree/main/ci-cd/gitlab-cicd) or follow this guide to get started.

## Building Your Application

You can build your application locally (or in a Pipeline) without giving Vercel access to the source code through `vercel build`. Vercel automatically detects your frontend framework and generates a `.vercel/output` folder conforming to the [Build Output API specification](https://vercel.com/docs/build-output-api/v3).

`vercel build` allows you to build your project within your own CI setup, whether it be GitLab CI/CD or your own in-house CI, and upload _only_ those build artifacts (and not the source code) to Vercel to create a deployment.

## Configuring GitLab CI/CD for Vercel

`vercel deploy --prebuilt` skips the build step on Vercel and uploads the previously generated `.vercel/output` folder from the CI/CD Pipeline.

Let’s create our CI/CD Pipeline by creating a new file `.gitlab-ci.yml`:

`default: image: node:22 deploy_preview: stage: deploy except: - main script: - npm install --global vercel - vercel pull --yes --environment=preview --token=$VERCEL_TOKEN - vercel build --token=$VERCEL_TOKEN - vercel deploy --prebuilt --token=$VERCEL_TOKEN deploy_production: stage: deploy only: - main script: - npm install --global vercel - vercel pull --yes --environment=production --token=$VERCEL_TOKEN - vercel build --prod --token=$VERCEL_TOKEN - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN`

This pipeline has two triggers:

- One that creates preview environments on commits pushed to a git branch
  
- Another that creates production environments on commits to the `main` branch
  

Finally, let’s add the required values from Vercel as CI/CD variables in GitLab:

1. Retrieve your [Vercel Access Token](https://vercel.com/support/articles/how-do-i-use-a-vercel-api-access-token)
   
2. Install the [Vercel CLI](https://vercel.com/cli) and run `vercel login`
   
3. Inside your folder, run `vercel link` to create a new Vercel project
   
4. Inside the generated `.vercel` folder, save the `projectId` and `orgId` from the `project.json`
   
5. Inside GitLab, add `VERCEL_TOKEN`, `VERCEL_ORG_ID`, and `VERCEL_PROJECT_ID` as [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/).
   

## Deploying Your Vercel Application with GitLab CI/CD

Now that your Vercel application is configured with GitLab CI/CD, you can try out the workflow:

- Create a new merge request to your GitLab repository
  
- GitLab CI/CD will recognize the change and use the Vercel CLI to build your application
  
- The pipeline uploads the build output to Vercel and creates a Preview Deployment
  
- When the merge request is merged, a Production build is created and deployed
  

Every merge request will now automatically have a Preview Deployment attached. If the merge request needs to be rolled back, you can revert and merge the MR and Vercel will start a new Production build back to the old git state.

## Adding branch details to the Vercel dashboard

By default, the branch information is not passed to Vercel from the CLI deployments. However, you can use the `--meta` (`-m`) option in the deploy command to add the branch details:

`vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN -m gitlabDeployment="1" -m gitlabCommitRef="main"`

More details are in this [guide](https://vercel.com/guides/branch-variables-and-domains-not-linked-to-cli-deployments).