Deploy to Vercel from a Selfhosted Gitlab instance

In this guide, we are deploying a Next.js application to Vercel from a local GitLab instance using CI/CD and a custom runner.

Prerequisites

• A GitLab instance running with Docker & Portainer (in the Cloud or on a local network)
• Node.js and npm installed locally on your PC
• A Vercel account
• A Next.js project

Prepare Vercel for CLI Deployments

1. Install Vercel Cli on your Computer

 npm i -g vercel

2. Login to your Vercel Account

vercel login

• This should open your browser, where you have to login to your Vercel account.
• Once logged in, you will get a success message. You can return to your console.

3. Create a Vercel project by running this command

vercel 

• you can continue with the basic options, except for 'Link to your existing project?' enter 'n' for no.

4. open the .vercel directory on your project on the machine, there should be your projectId and orgId.

Create a GitLab Project and Push Your Code

• to create a GitLab project open your GitLab's dashboard
• Click on the "New project' button
• Set the same project name as your Next.js project.
• Set the access level for your Project and remove the checkmark for initialize the repository with a README.

Setup your CI / CD pipeline

1. Head to Vercel and create a new account token

• Set a custom name for the token so you can recognise it later.
• Select the scopes you want to grant the token
• set an expiration day.
• copy your token and paste it somewhere safe. For security reasons this token cannot be shown a second time.

2. Set your environment variables in GitLab

• Head back to Gitlab, open your project and navigate to your projects settings > CI/CD > Variables
• create a variable for your Token: enter VERCEL_TOKEN under Key and under Value paste your Token
• create a variable for your Project ID: enter VERCEL_PROJECT_ID under Key and under Value paste your projectId from the project.json file
• create a variable for your Org ID: enter VERCEL_ORG_ID under Key and under Value paste your projectId from the project.json file

Set Up a GitLab Runner

1. Login to your portainer web console - if you havent installed Portainer yet, check out my other guide - i promise, its quick
2. Open your Docker environment
3. Click on Containers in the sidebar, then click Add container in the top right
4. Specify a name for the runner, in my case i called it testrunner, because i will delete it after the guide.
5. Enter the GitLab Runner image

gitlab/gitlab-runner:latest

6. on the bottom open Volumes and map additional volume:

• under container paste this: /var/run/docker.sock and click on bind
• under host also paste this: /var/run/docker.sock

1. select your GitLab's network in the Network tab
2. in the Restart policy tab select 'always'
3. Deploy the container
4. Click on Console and connect as root
5. Paste this snippet replace YOURGITLABDOMAIN.COM with your domain like gitlab.clickdavid.com

openssl s_client -showcerts -connect YOURGITLABDOMAIN.COM:443 -servername YOURGITLABDOMAIN.COM < /dev/null 2>/dev/null | openssl x509 -outform PEM > /etc/gitlab-runner/certs/YOURGITLABDOMAIN.COM.crt

11. Return back to your GitLab project, click settings > CI/CD
12. Go to Runners > Create a Runner
13. configure your runner: tags: docker, enable Run untagged jobs, set a runner description and click on Create runner
14. Copy the Snippet shown in Step 1
15. Paste this snippet in the portainer console
16. Click enter, when it asks your GitLab instance url
17. Enter the name for the runner
18. Set the executor to docker
19. Enter following default image: node:22.14.0
20. Start the runner with:

gitlab-runner run

Create the Ci file in your Projects root directory

1. Create the .gitlab-ci.yml file in your projects root with following contents:

stages:
  - build
  - deploy

.standard-rules:
  rules:
    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH

frontend-build-job:
  stage: build
  image: node:22.14.0
  script:
    - npm install
    - npm run build

frontend-deploy-job:
  stage: deploy
  image: node:22.14.0
  script:
    - npx vercel --prod --token $VERCEL_TOKEN --yes

2. Commit & Push the changes to your main branch

git add .
git commit -m "testing deployment"
git push --set-upstream https://YOURGITLABINSTANCE.COM/david/testproject.git master

If you found this guide useful, please consider subscribing or leaving a tip. Your support helps me keep sharing these kind guides!