GitLab CI/CD pipeline with manual Vercel deployment

For the past years I’ve been hoping between GitHub and GitLab for hosting my code. They both have options to use CI/CD runners that will take our recent commits, run tests, and optionally deploy the results.

Initially I started building this website with NextJS, but I didn’t want it to run build and deployment steps on the Vercel platform - I wanted to have it fully controlled by me.

I assume You already know what CI/CD pipelines are, and I want to show You how I managed my jobs and the whole pipeline with manual deployment with GitLab.

Bear in mind - I’m a total noob when it comes to DevOps topics. I’m still learning these things and I highly recommend it to You. It is a lot of fun, believe me ! 🤓

How the pipeline looks

1
image: oven/bun:latest
2

3
stages:
4
  - install
5
  - quality
6
  - build
7
  - deploy
8

9
variables:
10
  NODE_ENV: "production"
11
  NEXT_TELEMETRY_DISABLED: "1"
12
  GIT_DEPTH: 10
13
  GIT_STRATEGY: fetch
14

15
workflow:
16
  auto_cancel:
17
    on_new_commit: none
18
  rules:
19
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
20
      when: never
21
    - when: always
22

23
# Global cache configuration
24
cache:
25
  key:
26
    files:
27
      - bun.lockb
28
  paths:
29
    - node_modules/
30
    - .next/
31
  policy: pull
32

33
# 1. Install dependencies
34
install_dependencies:
35
  stage: install
36
  script:
37
    - bun install --frozen-lockfile
38
  cache:
39
    key:
40
      files:
41
        - bun.lockb
42
    paths:
43
      - node_modules/
44
      - .next/
45
    policy: pull-push
46

47
# Shared configuration for quality jobs
48
.quality_template: &quality_config
49
  stage: quality
50
  needs:
51
    - job: install_dependencies
52
      optional: true
53

54
lint:
55
  <<: *quality_config
56
  script:
57
    - bun run lint:stylish
58
    - bun run lint:types
59

60
type-check:
61
  <<: *quality_config
62
  script:
63
    - bun run check-types
64

65
# Template for common build settings
66
.build_template: &build_config
67
  stage: build
68
  needs:
69
    - job: install_dependencies
70
      optional: true
71
  cache:
72
    key:
73
      files:
74
        - bun.lockb
75
    paths:
76
      - node_modules/
77
      - .next/
78
    policy: pull-push
79

80
# JOB A: Validation Build (Runs on all branches EXCEPT main)
81
# Purpose: Check if app builds correctly, update cache, no deploy artifacts.
82
build:validate:
83
  <<: *build_config
84
  rules:
85
    - if: $CI_COMMIT_BRANCH != "main"
86
  script:
87
    - echo "Running standard build for validation (no Vercel deploy)."
88
    - bun run build
89
  artifacts:
90
    paths:
91
      - .next/
92
    expire_in: 1 day
93

94
# JOB B: Production Build (Runs ONLY on main)
95
# Purpose: Create Vercel artifacts for deployment.
96
build:vercel_production:
97
  <<: *build_config
98
  rules:
99
    - if: $CI_COMMIT_BRANCH == "main"
100
  script:
101
    - echo "Building for Vercel Production..."
102
    - bun install --global vercel
103
    - verify_installation
104
    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
105
    - vercel build --prod --token=$VERCEL_TOKEN
106
  artifacts:
107
    paths:
108
      - .vercel/output
109
      - .next/
110
    expire_in: 1 day
111

112
deploy:production:
113
  stage: deploy
114
  # Explicitly depends on the production build job
115
  needs: ["build:vercel_production"]
116
  rules:
117
    - if: $CI_COMMIT_BRANCH == "main"
118
  resource_group: production
119
  script:
120
    - echo "Deploying prebuilt artifacts to Vercel..."
121
    - bun install --global vercel
122
    - vercel deploy --prebuilt --prod --token=$VERCEL_TOKEN
123
      -m gitlabCommitRef=$CI_COMMIT_REF_NAME
124
      -m gitlabCommitSha=$CI_COMMIT_SHORT_SHA
125
      -m gitlabPipeline=$CI_PIPELINE_URL
126
      -m gitlabUser=$GITLAB_USER_LOGIN

Now since we already have the whole .gitlab-ci.yml file here, let’s break it down into smaller pieces.

Prepare container and stages

The most important thing that we have to do is to tell the container (where our code will run) which image it should use. In this example I’m using bun to run and build my codebase. You can use bun, node, ruby — whatever You actually need.

This is always kind of an entry point for our builds.

1
image: oven/bun:latest
2

3
stages:
4
  - install
5
  - quality
6
  - build
7
  - deploy
8

9
variables:
10
  NODE_ENV: "production"
11
  NEXT_TELEMETRY_DISABLED: "1"
12
  GIT_DEPTH: 10
13
  GIT_STRATEGY: fetch

image: tells which container should be pulled from Docker with an already prepared environment. This can be bun, node, ruby, etc.
stages: allows the pipeline to group up jobs into smaller chunks called stages for clarity
variables: these are the variables that will be set during our build process where GIT_DEPTH and GIT_STRATEGY are to tell the pipeline how it should fetch our codebase from the repository.

You can read more about variables on GitLab Docs(opens in new tab).

Workflow and cache configuration

1
workflow:
2
  auto_cancel:
3
    on_new_commit: none
4
  rules:
5
    # Don't run merge request pipelines, only branch pipelines
6
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
7
      when: never
8
    # Run for all other cases (branch pushes, etc.)
9
    - when: always
10

11
# Global cache configuration
12
cache:
13
  key:
14
    files:
15
      - bun.lockb
16
  paths:
17
    - node_modules/
18
    - .next/
19
  policy: pull

workflow: allows us to control how our pipelines run. We can have rules, auto_cancel and many many more GitLab workflow(opens in new tab). In this example we want to prevent the pipeline from being cancelled when we push a new commit fast, and we tell the pipeline to avoid running on the merge request event, so basically it will run when we push a new branch to our origin.
cache: this is an important part where we tell the pipeline what it should “save” in between jobs and save it as an artifact to be pulled by other jobs without the need to reinstall everything.

Now the cool stuff

The main “meat” of the pipeline are the jobs themselves here.

1
install_dependencies:
2
  stage: install
3
  script:
4
    - bun install --frozen-lockfile
5
  cache:
6
    key:
7
      files:
8
        - bun.lockb
9
    paths:
10
      - node_modules/
11
      - .next/
12
    policy: pull-push
13

14
.quality_template: &quality_config
15
  stage: quality
16
  needs:
17
    - job: install_dependencies
18
      optional: true
19

20
lint:
21
  <<: *quality_config
22
  script:
23
    - bun run lint:stylish
24
    - bun run lint:types
25

26
type-check:
27
  <<: *quality_config
28
  script:
29
    - bun run check-types
30

31
# Template for common build settings
32
.build_template: &build_config
33
  stage: build
34
  needs:
35
    - job: install_dependencies
36
      optional: true
37
  cache:
38
    key:
39
      files:
40
        - bun.lockb
41
    paths:
42
      - node_modules/
43
      - .next/
44
    policy: pull-push
45

46
# JOB A: Validation Build (Runs on all branches EXCEPT main)
47
# Purpose: Check if app builds correctly, update cache, no deploy artifacts.
48
build:validate:
49
  <<: *build_config
50
  rules:
51
    - if: $CI_COMMIT_BRANCH != "main"
52
  script:
53
    - echo "Running standard build for validation (no Vercel deploy)."
54
    - bun run build
55
  artifacts:
56
    paths:
57
      - .next/
58
    expire_in: 1 day
59

60
# JOB B: Production Build (Runs ONLY on main)
61
# Purpose: Create Vercel artifacts for deployment.
62
build:vercel_production:
63
  <<: *build_config
64
  rules:
65
    - if: $CI_COMMIT_BRANCH == "main"
66
  script:
67
    - echo "Building for Vercel Production..."
68
    - bun install --global vercel
69
    - verify_installation
70
    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
71
    - vercel build --prod --token=$VERCEL_TOKEN
72
  artifacts:
73
    paths:
74
      - .vercel/output
75
      - .next/
76
    expire_in: 1 day

Let’s break down this to the smaller parts.

Installation and cache

1
install_dependencies:
2
  stage: install
3
  script:
4
    - bun install --frozen-lockfile
5
  cache:
6
    key:
7
      files:
8
        - bun.lockb
9
    paths:
10
      - node_modules/
11
      - .next/
12
    policy: pull-push

We install_dependencies just like we would do locally
- stage - tells which stage it should be “put into” (which we prepared earlier)
- script - we pass the command that we want to run
- cache - we tell the runner what we want to cache and save as an artifact

Quality check

1
.quality_template: &quality_config
2
  stage: quality
3
  needs:
4
    - job: install_dependencies
5
      optional: true
6

7
lint:
8
  <<: *quality_config
9
  script:
10
    - bun run lint:stylish
11
    - bun run lint:types
12

13
type-check:
14
  <<: *quality_config
15
  script:
16
    - bun run check-types

.quality_template - we prepare a custom template for scripts that we will use within this step and save it as &quality_config.
- stage: set in which stage it should run (defined at the beginning)
- needs: allows us to run this stage ONLY when install_dependencies are done
lint: we define the lint stage that will be part of the .quality_template.
- scripts: defined scripts that will run and lint our code, in this case these scripts are defined in package.json
type-check: type check step to run the TypeScript compiler to check if all types are okay.
- scripts: same as above with a different command 😃

Actual build and deployment

1
# Template for common build settings
2
.build_template: &build_config
3
  stage: build
4
  needs:
5
    - job: install_dependencies
6
      optional: true
7
  cache:
8
    key:
9
      files:
10
        - bun.lockb
11
    paths:
12
      - node_modules/
13
      - .next/
14
    policy: pull-push
15

16
# JOB A: Validation Build (Runs on all branches EXCEPT main)
17
# Purpose: Check if app builds correctly, update cache, no deploy artifacts.
18
build:validate:
19
  <<: *build_config
20
  rules:
21
    - if: $CI_COMMIT_BRANCH != "main"
22
  script:
23
    - echo "Running standard build for validation (no Vercel deploy)."
24
    - bun run build
25
  artifacts:
26
    paths:
27
      - .next/
28
    expire_in: 1 day
29

30
# JOB B: Production Build (Runs ONLY on main)
31
# Purpose: Create Vercel artifacts for deployment.
32
build:vercel_production:
33
  <<: *build_config
34
  rules:
35
    - if: $CI_COMMIT_BRANCH == "main"
36
  script:
37
    - echo "Building for Vercel Production..."
38
    - bun install --global vercel
39
    - verify_installation
40
    - vercel pull --yes --environment=production --token=$VERCEL_TOKEN
41
    - vercel build --prod --token=$VERCEL_TOKEN
42
  artifacts:
43
    paths:
44
      - .vercel/output
45
      - .next/
46
    expire_in: 1 day

In this case I wanted to experiment a little bit and created two job variants:

build:validate - will run for all branches except main to check if our pushed code works
build:vercel_production - will run only on the main branch, where it will build and deploy our code via Vercel CLI

.build_template: &build_config - we prepare a build template so we can simply reuse it however we want.
- this build will use the &build_config setup so we can avoid duplicated steps within our jobs
build:vercel_production - we run &build_config and check if we are on the main branch:
- if we are on the main branch, the job runs a new set of scripts to install vercel, verify_installation, vercel pull information about our projects on Vercel, and finally vercel build --prod to build our code for the production environment.

This last step is where the magic happens. Within our script we pass the --token flag with $VERCEL_TOKEN that will authenticate us on Vercel and deploy the code to our project.

GitLab Variables

GitLab allows us to set variables that will be available for all our pipelines at all times. For this we need to get to:

Our repo -> Setting -> CI/CD -> Variables

From there we will have a table where we can Add variable and in the drawer on the right we have to set:

Key - token key name
Values - token value (secret, auth_token, or any token we need)

These tokens can be found on the Vercel dashboard. In order to make these pipelines deploy our code to Vercel we need to set:

VERCEL_ORG_ID - found in team settings (the naming could have changed to Team ID)
VERCEL_PROJECT_ID - found in project settings
VERCEL_TOKEN - found in our user settings under Tokens

You can read more about this in Vercel Knowledge Base(opens in new tab).

Is that all ?

Yes, that’s all You need to run Your code through the pipeline to build, lint/test, and deploy Your codebase straight to Vercel.

Is this a perfect pipeline ? Of course NOT, although I really enjoyed building it from the ground up, step by step, and I suggest You try it as well. Currently with AI it is much easier to initially start and then build on top of it and make it better or optimize it to our needs.

Remember - experiment, have fun, build and break stuff while enjoying the whole process. 🤓