Vercel for GitLab automatically deploys your GitLab projects with Vercel, providing Preview Deployment URLs, and automatic Custom Domain 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
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.
You can view the completed example here 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.
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
1default:2image: node:16.16.034deploy_preview:5stage: deploy6except:7- main8script:9- npm install --global vercel10- vercel pull --yes --environment=preview --token=$VERCEL_TOKEN11- vercel build --token=$VERCEL_TOKEN12- vercel deploy --prebuilt --token=$VERCEL_TOKEN1314deploy_production:15stage: deploy16only:17- main18script:19- npm install --global vercel20- vercel pull --yes --environment=production --token=$VERCEL_TOKEN21- vercel build --prod --token=$VERCEL_TOKEN22- 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
Finally, let’s add the required values from Vercel as CI/CD variables in GitLab:
- Retrieve your Vercel Access Token
- Install the Vercel CLI and run
- Inside your folder, run
vercel linkto create a new Vercel project
- Inside the generated
.vercelfolder, save the
- Inside GitLab, add
VERCEL_PROJECT_IDas CI/CD 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.