Files
e2e/docs/ci/gitlab.mdx
Kacper KapuściakandOskar Kwaśniewski d593863b41 feat(cli): write a GitHub Actions or GitLab CI/CD pipeline in e2e init (#1647)
* feat(cli): write a GitHub Actions or GitLab CI/CD pipeline in e2e init

e2e init asks for a CI pipeline in a project with the web engine (--ci github-actions|gitlab|none). It writes one job for the project's package manager and Node version that installs Chromium, runs e2e run, and keeps the report, and names the secret or CI/CD variable for the model key. It never overwrites a pipeline file; beside an existing .gitlab-ci.yml it writes a file to include.

* fix(cli): handle cubic's findings on the init CI step

Exact GitLab stage names, a distinct job name beside an existing e2e job, loopback baseURL in an existing config, no writes through a symlinked .github or .gitlab, --ci none in the skill, gitlab in the telemetry comment, and the GitLab Node image's major version in the docs.

* refactor(cli): keep the init CI pipelines as YAML templates

The GitHub Actions workflow and the GitLab job live in packages/e2e/templates/ci/ as complete pipelines for npm at the repository root, linted as they are. init loads them with the yaml package's Document API and edits a copy for the project's package manager, folders, Node version, secrets, and target, keeping the comments. The pinned actions now live only in the templates.

* fix(cli): point setup-bun at the package.json of a project in a subfolder

* docs(ci): link the GitLab page from init and the GitLab template

* feat(cli): write the iOS and Android CI jobs in e2e init

init writes one job per platform the config's targets run on: web targets in the web job, iOS and Android targets in their own jobs, which build the app, boot a simulator or an emulator, and install the app. Targets come from the new config, or from loading an existing one after the confirmation and the install. Expo and bare React Native apps get their build; any other app gets a step to replace. GitHub's mobile jobs follow e2e-inc/e2e-react-native's workflow; GitLab's run on self-managed runners.

* fix(cli): reinstall an emulator system image that holds no image in the Android CI job

* fix(cli): handle cubic's findings on the mobile CI jobs

Upload the emulator log from the GitLab Android job, count peer and optional engine dependencies, ask nothing for a new config with no engine, key caches on Bun's bun.lockb when that is the lockfile, and run the symlink test with a Windows junction.

* fix(cli): put current Android command-line tools in place before the emulator image

The runner image's cmdline-tools can be older than the system image's package format, and android-emulator-runner uses them to create the AVD, which then fails with 'contains no system images'. The Android job downloads command-line tools 23.0, checks its SHA-256, and installs the image with it.

* fix(cli): import moved core modules from @e2e-dev/core in init

* fix(cli): count a pipeline as set up only when a command runs e2e run

init matched the text 'e2e run' anywhere in a workflow, so a comment or a step name such as 'our old e2e runner' made --ci write nothing. It now reads the commands (run, script, before_script, after_script) from the parsed YAML and matches e2e run as words of their own.

Also: --ci help and the InitOptions JSDoc say tests on every platform, and yaml is pinned exactly like the other dependencies.

* chore(ci): bump setup-node and upload-artifact pins in the init templates, docs, and skill

docs/ci/vercel-previews.mdx on main pins setup-node v7.1.0 and upload-artifact v7.0.2, the pins this repository's own workflows run. The templates, three docs pages, and the skill still had v7.0.0 and v7.0.1, so the pin test failed once main was merged in.

---------

Co-authored-by: Oskar Kwaśniewski <oskar@okwasniewski.com>
2026-11-16 17:21:49 +00:00

262 lines
9.7 KiB
Plaintext

---
title: GitLab CI/CD
description: Run web, iOS, and Android tests on GitLab CI/CD, show the results in the merge request, and run only the tests a merge request can affect.
---
import { SetupPrompt } from '../snippets/setup-prompt-card.jsx';
export const setupPrompt = `Add a GitLab CI/CD pipeline that runs this project's e2e tests. Docs: \`https://e2e.com/docs/ci/gitlab.md\` and \`https://e2e.com/docs/ci.md\`
1. Read both pages. Use the web job for web targets and the iOS and Android jobs for mobile targets.
2. Add the jobs to \`.gitlab-ci.yml\`, or to an included file when the project already has one. Adapt them to this project: package manager, Node version, how the app starts or builds, and the app paths.
3. For a mobile job, ask me for the tags of the self-managed runners to use.
4. List the CI/CD variables the jobs read, such as the model key, and ask me to add them.
5. After I push, read the job log and fix errors until the pipeline passes.`;
These jobs run web targets on GitLab's hosted Linux runners, and iOS and
Android targets on your own runners. For CI defaults, model keys, and exit
codes, see [Continuous integration](/ci).
`e2e init --ci gitlab` writes these jobs for your targets and package
manager, with the build for an Expo or bare React Native app; see
[CI pipeline](/reference/cli#ci-pipeline).
<SetupPrompt>
<Prompt description={setupPrompt} children={setupPrompt} actions={["copy", "cursor"]} />
</SetupPrompt>
## Web
This job runs deterministic and agent tests, in each merge request and on
each push to the default branch. It assumes a config
[command](/web#starting-your-app) that starts the app. Use the `node` image
for your project's Node version:
```yaml title=".gitlab-ci.yml" expandable
e2e:
image: node:26
interruptible: true
timeout: 30 minutes
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
- if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH
variables:
APP_URL: http://127.0.0.1:3000
PLAYWRIGHT_BROWSERS_PATH: $CI_PROJECT_DIR/.cache/ms-playwright
cache:
key:
files:
- package-lock.json
paths:
- .npm/
- .cache/ms-playwright/
script:
- npm ci --cache .npm --prefer-offline
- npx @e2e-dev/web install chromium --with-deps
- npx e2e run --reporter list,junit
artifacts:
when: always
expire_in: 7 days
paths:
- .e2e/report.json
- .e2e/junit.xml
- .e2e/results/
reports:
junit: .e2e/junit.xml
```
The rules are on the job, not in a `workflow:` block, so the same job works
in a pipeline of its own or [beside your other jobs](#add-it-to-an-existing-pipeline).
GitLab caches only paths inside the project, so `PLAYWRIGHT_BROWSERS_PATH`
moves the [browsers](/reference/web#installing-browsers) there. The cache
keeps them until the lockfile changes.
Make the app's command listen on `127.0.0.1`, the host `APP_URL` names. In
the container, a dev server that listens on `localhost`, such as Vite's,
can bind only `::1`. Then e2e can't reach it and the run fails with
`APP_UNREACHABLE`.
`reports: junit` shows the results in the merge request widget and on the
pipeline's **Tests** tab. `when: always` keeps the reports when a test fails
too.
On GitLab.com, a new account must verify its identity before hosted runners
take its jobs. Until then, each pipeline fails without starting a job.
## Add it to an existing pipeline
When the project already has a `.gitlab-ci.yml`, put the job in a file of
its own, such as `.gitlab/e2e.gitlab-ci.yml`. Then include it from
`.gitlab-ci.yml`:
```yaml title=".gitlab-ci.yml"
include:
- local: .gitlab/e2e.gitlab-ci.yml
```
A job with no `rules` runs only in branch pipelines. So a merge request
pipeline runs the `e2e` job alone, and your other jobs still run once per
push.
## Model key
Add the model key, such as `AI_GATEWAY_API_KEY`, under **Settings > CI/CD >
Variables**, with the visibility **Masked and hidden**. Or use the
[GitLab CLI](https://gitlab.com/gitlab-org/cli), which reads the value from
standard input:
```bash
printf %s "$AI_GATEWAY_API_KEY" | glab variable set AI_GATEWAY_API_KEY --masked --hidden --raw
```
Add user credentials, such as `E2E_USER_ADMIN_PASSWORD`, the same way. Each
job gets them as environment variables.
- Clear **Expand variable reference** (`--raw` does this). Otherwise GitLab
rejects a masked value with `$` and some other characters.
- GitLab masks only values of 8 or more characters, on one line, with no
spaces. Use **Visible** for a value it can't mask, such as a short
username.
- Clear **Protect variable** unless the tests run only on protected
branches. GitLab gives a protected variable only to pipelines on
protected branches and tags.
- A merge request from a fork runs in the fork's project, with none of
your variables. When a member runs it in your project, its code can read
the key. Do that only for code you trust.
[Commit the replay cache](/cache#commit-the-replay-cache) to make fewer
model calls. A replayed `agent.act` calls no model; each `agent.assert`
still does.
## Run only affected tests
To let a [test filter](/filters) leave out the tests a merge request can't
affect, pass the merge request's base to `--changed-since`. Add
`GIT_DEPTH: 0` to the job's `variables` to fetch the full history. Then
replace the `npx e2e run` line with this one, which skips the flag in merge
trains:
```yaml
script:
# ...
- |
if [ -n "$CI_MERGE_REQUEST_IID" ] && [ "$CI_MERGE_REQUEST_EVENT_TYPE" != merge_train ]; then
set -- --changed-since "${CI_MERGE_REQUEST_TARGET_BRANCH_SHA:-$CI_MERGE_REQUEST_DIFF_BASE_SHA}"
fi
npx e2e run --reporter list,junit "$@"
```
`CI_MERGE_REQUEST_TARGET_BRANCH_SHA` is set in merged results pipelines,
and `CI_MERGE_REQUEST_DIFF_BASE_SHA` in the others. On the default branch
the whole suite runs. See
[Add the decision filter](/filters#add-the-decision-filter).
## Sharding
`parallel` runs one job for each [shard](/ci#sharding). GitLab merges the
JUnit reports of all shards in the merge request widget:
```yaml
e2e:
parallel: 3
script:
# ...
- npx e2e run --shard $CI_NODE_INDEX/$CI_NODE_TOTAL --reporter list,junit
```
A shard with no test fails with `NO_TESTS`. If the run can select fewer
tests than shards, add `--pass-with-no-tests`.
## iOS and Android
Run the mobile jobs on self-managed runners with the shell executor: a Mac
with Xcode for iOS, and Linux with KVM, the JDK your Gradle build needs, and
the Android SDK for Android.
GitLab's hosted macOS runners are headless and don't support `testmanagerd`,
which XCUITest needs. Its hosted Linux runners don't list KVM.
These jobs follow the rules in [Mobile jobs](/ci#mobile-jobs). Replace the
`tags` with your runners' tags. The Android job boots an AVD named `e2e`
that you create on the runner.
```yaml title=".gitlab-ci.yml" expandable
.e2e-mobile:
timeout: 60m
interruptible: true
artifacts:
when: always
expire_in: 7 days
paths:
- .e2e/
reports:
junit: .e2e/junit.xml
e2e-ios:
extends: .e2e-mobile
tags: [macos]
script:
- npm ci
- (cd ios && pod install)
- |
xcodebuild -workspace ios/MyApp.xcworkspace -scheme MyApp \
-configuration Release -sdk iphonesimulator \
-destination 'generic/platform=iOS Simulator' \
-derivedDataPath build
- export E2E_DEVICE=$(xcrun simctl create e2e "iPhone 17" com.apple.CoreSimulator.SimRuntime.iOS-26-5)
- echo "$E2E_DEVICE" > .simulator-udid
- xcrun simctl bootstatus "$E2E_DEVICE" -b
- xcrun simctl install "$E2E_DEVICE" build/Build/Products/Release-iphonesimulator/MyApp.app
- npx e2e run --target ios --reporter list,junit
after_script:
- xcrun simctl delete "$(cat .simulator-udid)"
e2e-android:
extends: .e2e-mobile
tags: [linux-kvm]
script:
- npm ci
- (cd android && ./gradlew :app:assembleRelease)
- mkdir -p .e2e
- PORT=$((5554 + 2 * CI_CONCURRENT_ID))
- export E2E_DEVICE=emulator-$PORT
- adb -s $E2E_DEVICE emu kill || true
- $ANDROID_HOME/emulator/emulator -avd e2e -read-only -port $PORT -no-window -no-audio -no-boot-anim -no-snapshot -gpu swiftshader_indirect > .e2e/emulator.log 2>&1 &
- timeout 300 adb -s $E2E_DEVICE wait-for-device
- timeout 300 sh -c 'until [ "$(adb -s $E2E_DEVICE shell getprop sys.boot_completed | tr -d "\r")" = 1 ]; do sleep 2; done'
- adb -s $E2E_DEVICE install -r android/app/build/outputs/apk/release/app-release.apk
- npx e2e run --target android --reporter list,junit
after_script:
- adb -s emulator-$((5554 + 2 * CI_CONCURRENT_ID)) emu kill
```
Each target names its device with `device: process.env.E2E_DEVICE` in
`mobile()`. Then the run drives the device this job booted, never a device
left over from another job on the same machine.
GitLab runs all `script` lines in one shell, so the emulator and
`E2E_DEVICE` stay available to the next lines. `after_script` runs in a new
shell after a failed `script` too, but not after a timeout, so a timed-out
job can leave its device running. The Android job takes its port from
`CI_CONCURRENT_ID`, so jobs running at the same time on one runner get
their own emulator, and it stops an emulator a timed-out job left on that
port. `-read-only` lets several emulators start from one AVD. The job writes the emulator's log
to `.e2e/emulator.log`, so a failed boot shows in the artifacts. A
self-managed runner keeps `~/.agent-device` between jobs, so the XCUITest
runner is built only on the first run.
To run without a simulator or emulator on the runner, lease devices from
a [hosted device service](/mobile#hosted-devices).
## Next
<CardGroup cols={2}>
<Card title="Continuous integration" icon="rotate" href="/ci">
CI defaults, sharding, reruns, and exit codes.
</Card>
<Card title="Test filters" icon="filter" href="/filters">
Run only the tests a merge request can affect.
</Card>
</CardGroup>