1# GitLab CI/CD Configuration
2 
3## Table of Contents
4 
51. [Key Commands](#key-commands)
62. [Patterns](#patterns)
73. [Decision Guide](#decision-guide)
84. [Anti-Patterns](#anti-patterns)
95. [Troubleshooting](#troubleshooting)
10 
11> **When to use**: Running Playwright tests in GitLab pipelines on merge requests, merges to main, or scheduled pipelines.
12 
13## Key Commands
14 
15```bash
16npx playwright install --with-deps    # install browsers + OS deps
17npx playwright test --shard=1/4       # run 1 of 4 parallel shards
18npx playwright merge-reports ./blob-report  # merge shard results
19npx playwright test --reporter=dot    # minimal output for CI logs
20```
21 
22## Patterns
23 
24### Basic Pipeline Configuration
25 
26**Use when**: Any GitLab project with Playwright tests.
27 
28```yaml
29# .gitlab-ci.yml
30image: mcr.microsoft.com/playwright:v1.48.0-noble
31 
32stages:
33  - install
34  - test
35  - report
36 
37variables:
38  CI: "true"
39  npm_config_cache: "$CI_PROJECT_DIR/.npm"
40 
41cache:
42  key:
43    files:
44      - package-lock.json
45  paths:
46    - .npm/
47    - node_modules/
48 
49setup:
50  stage: install
51  script:
52    - npm ci
53  artifacts:
54    paths:
55      - node_modules/
56    expire_in: 1 hour
57 
58e2e:
59  stage: test
60  needs: [setup]
61  script:
62    - npx playwright test
63  artifacts:
64    when: always
65    paths:
66      - playwright-report/
67      - test-results/
68    expire_in: 14 days
69  rules:
70    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
71    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
72```
73 
74### Sharded Parallel Execution
75 
76**Use when**: Test suite exceeds 10 minutes. GitLab's `parallel` keyword splits across jobs automatically.
77**Avoid when**: Suite runs under 5 minutes.
78 
79```yaml
80image: mcr.microsoft.com/playwright:v1.48.0-noble
81 
82stages:
83  - install
84  - test
85  - report
86 
87variables:
88  CI: "true"
89  npm_config_cache: "$CI_PROJECT_DIR/.npm"
90 
91cache:
92  key:
93    files:
94      - package-lock.json
95  paths:
96    - .npm/
97    - node_modules/
98 
99setup:
100  stage: install
101  script:
102    - npm ci
103  artifacts:
104    paths:
105      - node_modules/
106    expire_in: 1 hour
107 
108e2e:
109  stage: test
110  needs: [setup]
111  parallel: 4
112  script:
113    - npx playwright test --shard=$CI_NODE_INDEX/$CI_NODE_TOTAL
114  artifacts:
115    when: always
116    paths:
117      - blob-report/
118    expire_in: 1 hour
119  rules:
120    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
121    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
122 
123combine-reports:
124  stage: report
125  needs: [e2e]
126  when: always
127  script:
128    - npx playwright merge-reports --reporter=html ./blob-report
129  artifacts:
130    when: always
131    paths:
132      - playwright-report/
133    expire_in: 14 days
134```
135 
136**Config for sharded pipelines:**
137 
138```typescript
139// playwright.config.ts
140export default defineConfig({
141  reporter: process.env.CI
142    ? [["blob"], ["dot"]]
143    : [["html", { open: "on-failure" }]],
144});
145```
146 
147### Environment Variables and Secrets
148 
149**Use when**: Tests need secrets (API keys, passwords) and should only run on merge requests or the default branch.
150 
151```yaml
152image: mcr.microsoft.com/playwright:v1.48.0-noble
153 
154stages:
155  - test
156 
157variables:
158  CI: "true"
159 
160e2e:staging:
161  stage: test
162  variables:
163    BASE_URL: $STAGING_URL
164    TEST_PASSWORD: $TEST_PASSWORD
165    API_KEY: $API_KEY
166  before_script:
167    - npm ci
168  script:
169    - npx playwright test
170  artifacts:
171    when: always
172    paths:
173      - playwright-report/
174      - test-results/
175    expire_in: 14 days
176  rules:
177    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
178    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
179    - when: manual
180      allow_failure: true
181```
182 
183**Setting variables in GitLab:**
184Navigate to **Settings > CI/CD > Variables** and add:
185 
186- `STAGING_URL` -- not masked, not protected
187- `TEST_PASSWORD` -- masked, protected
188- `API_KEY` -- masked, protected
189 
190### Multi-Browser Matrix
191 
192**Use when**: Running Chromium on MRs and all browsers on the default branch.
193 
194```yaml
195image: mcr.microsoft.com/playwright:v1.48.0-noble
196 
197stages:
198  - install
199  - test
200 
201variables:
202  CI: "true"
203 
204setup:
205  stage: install
206  script:
207    - npm ci
208  artifacts:
209    paths:
210      - node_modules/
211    expire_in: 1 hour
212 
213e2e:chromium:
214  stage: test
215  needs: [setup]
216  script:
217    - npx playwright test --project=chromium
218  artifacts:
219    when: always
220    paths:
221      - playwright-report/
222      - test-results/
223    expire_in: 14 days
224  rules:
225    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
226 
227e2e:all-browsers:
228  stage: test
229  needs: [setup]
230  parallel:
231    matrix:
232      - PROJECT: [chromium, firefox, webkit]
233  script:
234    - npx playwright test --project=$PROJECT
235  artifacts:
236    when: always
237    paths:
238      - playwright-report/
239      - test-results/
240    expire_in: 14 days
241  rules:
242    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
243```
244 
245### Services Integration (Database, Cache)
246 
247**Use when**: Tests need the application running alongside Playwright, or you need external services.
248 
249```yaml
250stages:
251  - test
252 
253e2e:integration:
254  stage: test
255  image: mcr.microsoft.com/playwright:v1.48.0-noble
256  services:
257    - name: postgres:latest
258      alias: db
259    - name: redis:latest
260      alias: cache
261  variables:
262    CI: "true"
263    DATABASE_URL: "postgresql://postgres:postgres@db:5432/testdb"
264    REDIS_URL: "redis://cache:6379"
265    POSTGRES_PASSWORD: "postgres"
266    POSTGRES_DB: "testdb"
267  before_script:
268    - npm ci
269    - npx prisma db push
270    - npx prisma db seed
271  script:
272    - npx playwright test
273  artifacts:
274    when: always
275    paths:
276      - playwright-report/
277      - test-results/
278    expire_in: 14 days
279  rules:
280    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
281    - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
282```
283 
284### Scheduled Nightly Regression
285 
286**Use when**: Full regression is too slow for every MR.
287 
288```yaml
289e2e:nightly:
290  stage: test
291  image: mcr.microsoft.com/playwright:v1.48.0-noble
292  before_script:
293    - npm ci
294  script:
295    - npx playwright test --grep @regression
296  artifacts:
297    when: always
298    paths:
299      - playwright-report/
300    expire_in: 30 days
301  rules:
302    - if: $CI_PIPELINE_SOURCE == "schedule"
303```
304 
305Set up the schedule in **CI/CD > Schedules**: `0 3 * * 1-5` (3 AM UTC, weekdays).
306 
307## Decision Guide
308 
309| Scenario                             | Approach                                               | Why                                                 |
310| ------------------------------------ | ------------------------------------------------------ | --------------------------------------------------- |
311| Simple project, < 5 min suite        | Single `test` job using Playwright Docker image        | No sharding overhead; artifacts capture report      |
312| Suite > 10 min                       | `parallel: N` with `--shard`                           | GitLab auto-assigns `CI_NODE_INDEX`/`CI_NODE_TOTAL` |
313| Merge request fast feedback          | Chromium only on MRs; all browsers on main             | 3x fewer pipeline minutes on MRs                    |
314| External services needed (DB, Redis) | `services:` keyword with Postgres/Redis images         | GitLab manages service lifecycle                    |
315| Secrets for staging environment      | GitLab CI/CD Variables (masked + protected)            | Never hardcode secrets in `.gitlab-ci.yml`          |
316| Full nightly regression              | Pipeline schedule (`CI_PIPELINE_SOURCE == "schedule"`) | Avoids blocking MR pipelines                        |
317| Report browsing                      | `artifacts:` with `paths: [playwright-report/]`        | Browse directly in GitLab job artifacts UI          |
318 
319## Anti-Patterns
320 
321| Anti-Pattern                                         | Problem                                                            | Do This Instead                                                           |
322| ---------------------------------------------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------- |
323| Not using the Playwright Docker image                | Installing browsers every run adds 1-2 minutes                     | Use `mcr.microsoft.com/playwright:v1.48.0-noble` as base image                   |
324| `artifacts: when: on_failure` only                   | No report when tests pass; can't verify results                    | Use `when: always` to capture reports regardless                          |
325| No `expire_in` on artifacts                          | Artifacts accumulate and consume storage                           | Set `expire_in: 14 days` for reports, `1 hour` for intermediate artifacts |
326| Hardcoding `CI_NODE_TOTAL` in shard flag             | Breaks when you change `parallel:` value                           | Use `--shard=$CI_NODE_INDEX/$CI_NODE_TOTAL`                               |
327| Skipping `needs:` between stages                     | Jobs wait for all previous stage jobs, not just their dependencies | Use `needs:` for precise dependency graphs                                |
328| Large `cache:` including `node_modules/` without key | Stale cache causes version conflicts                               | Key cache on `package-lock.json` hash                                     |
329 
330## Troubleshooting
331 
332### Browser launch fails: "Failed to launch browser"
333 
334**Cause**: Not using the Playwright Docker image, or using a version that doesn't match your `@playwright/test` version.
335 
336**Fix**: Match the Docker image tag to your Playwright version:
337 
338```yaml
339# Check your version: npm ls @playwright/test
340image: mcr.microsoft.com/playwright:v1.48.0-noble
341```
342 
343### Tests hang in GitLab runner: "Navigation timeout exceeded"
344 
345**Cause**: GitLab shared runners may have limited resources.
346 
347**Fix**: Reduce workers and increase timeouts:
348 
349```typescript
350export default defineConfig({
351  workers: process.env.CI ? 2 : undefined,
352  use: {
353    navigationTimeout: process.env.CI ? 30_000 : 15_000,
354  },
355});
356```
357 
358### Pipeline runs on every push, not just merge requests
359 
360**Cause**: Missing `rules:` configuration.
361 
362**Fix**: Add explicit rules:
363 
364```yaml
365rules:
366  - if: $CI_PIPELINE_SOURCE == "merge_request_event"
367  - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
368```
369 
370### Services (Postgres/Redis) not reachable from tests
371 
372**Cause**: Using `localhost` instead of the service alias.
373 
374**Fix**: Use the service alias as hostname:
375 
376```yaml
377services:
378  - name: postgres:latest
379    alias: db
380 
381variables:
382  DATABASE_URL: "postgresql://postgres:postgres@db:5432/testdb"
383```
384 
385### Merged report is empty after sharded run
386 
387**Cause**: Each shard job needs the `blob` reporter, not `html`.
388 
389**Fix**: Configure blob reporter for CI:
390 
391```typescript
392export default defineConfig({
393  reporter: process.env.CI
394    ? [["blob"], ["dot"]]
395    : [["html", { open: "on-failure" }]],
396});
397```
398