GitLab CI/CD Component
On this page
#GitLab CI/CD Component
#Introduction
The PrestaFlow GitLab CI/CD Component
runs your PrestaFlow test suites inside a GitLab pipeline. It is a straight port
of the GitHub Action — same
inputs, same upload endpoint on the backend (POST /ci/github-action, which is
provider-agnostic), same MR comment format. Optionally boot a full
PrestaShop Flashlight
instance, execute your suite, upload the report (with error and
visual-regression screenshots), and post (or update) a summary note on the
merge request.
#Installation
The component lives on GitHub (PrestaFlow/gitlab-component). GitLab's
Catalog include: - component: shorthand only resolves against
$CI_SERVER_FQDN (typically gitlab.com), so there are two ways to consume
it.
#Option A — mirror to gitlab.com (recommended)
Push this repository as a mirror to gitlab.com/prestaflow/ci, tag a release
on GitLab so the ref shows in the CI/CD Catalog listing, then in your
.gitlab-ci.yml:
1include:2 - component: gitlab.com/prestaflow/ci/prestaflow@v0.1.03 inputs:4 token: $PRESTAFLOW_TOKEN
#Option B — consume directly from GitHub
If you do not want to maintain a mirror, git clone the component in a
before_script and include: a local file:
1default: 2 before_script: 3 - if [ ! -d .prestaflow-component ]; then 4 git clone --depth 1 --branch v0.1.0 5 https://github.com/PrestaFlow/gitlab-component.git .prestaflow-component; 6 fi 7 8include: 9 - local: .prestaflow-component/templates/prestaflow.yml10 inputs:11 token: $PRESTAFLOW_TOKEN
Either way, the scripts run directly from the checked-out component
sources. The template's before_script also handles the clone in Option A,
so you never have to duplicate the logic.
#Quick start
Minimal .gitlab-ci.yml that runs the component on every pipeline:
1include:2 - component: gitlab.com/prestaflow/ci/prestaflow@v0.1.03 inputs:4 token: $PRESTAFLOW_TOKEN5 project_id: pk_01ABCDEF
Store your PrestaFlow API token as a masked CI/CD variable named
PRESTAFLOW_TOKEN (Settings → CI/CD → Variables). Replace pk_01ABCDEF with
your project's Product Key.
#Full example
1include: 2 - component: gitlab.com/prestaflow/ci/prestaflow@v0.1.0 3 inputs: 4 token: $PRESTAFLOW_TOKEN 5 project_id: pk_01ABCDEF 6 flashlight: "true" 7 ps_version: "9.0.0" 8 suites: "BackOffice,FrontOffice" 9 visual: "true"10 mr_comment: "true"11 12variables:13 # Required for MR comments — CI_JOB_TOKEN cannot post notes.14 GITLAB_TOKEN: $GITLAB_TOKEN
#Inputs reference
| Input | Default | Description |
|---|---|---|
api_url |
https://api.prestaflow.io |
PrestaFlow API base URL. |
token |
(required) | PrestaFlow API token — pass through a masked CI variable. |
project_id |
"" |
PrestaFlow project Product Key (pk_...). Optional if the token is scoped. |
execute |
"true" |
Run composer run prestaflow:json:file before upload. |
suites |
"" |
Comma-separated suite list (BackOffice,FrontOffice). Empty = all. |
flashlight |
"false" |
Start a PrestaShop Flashlight Docker instance. Requires docker:dind. |
ps_version |
"latest" |
Flashlight image tag (9.0.0, 8.1.7, latest). Ignored unless flashlight=true. |
flashlight_mount |
"auto" |
auto | root | modules | themes. Where the workspace is mounted inside PrestaShop. |
flashlight_init_scripts |
"" |
Path (absolute or relative to $CI_PROJECT_DIR) to a dir of init scripts, mounted at /tmp/init-scripts read-only. |
mr_comment |
"" (auto) |
Post/update the Merge Request note. Auto-detected: true on MR pipelines, false otherwise. |
upload_artifacts |
"true" |
Attach results.json + screenshots as GitLab artifacts. |
visual |
"true" |
Enable the visual-regression round-trip (download baselines before, upload actual/diff after). |
#Required CI/CD variables
| Variable | Required for | Notes |
|---|---|---|
PRESTAFLOW_TOKEN |
Uploading results | Mask it. Passed as token input. |
GITLAB_TOKEN |
MR comments | Project or personal access token with api scope. CI_JOB_TOKEN cannot post MR notes. |
#Outputs (dotenv)
The job writes prestaflow.env and exposes it via
artifacts:reports:dotenv, so any downstream job in the same pipeline can
consume the values as environment variables:
| Variable | Description |
|---|---|
PRESTAFLOW_REPORT_ID |
PrestaFlow report ID. |
PRESTAFLOW_REPORT_URL |
URL of the report on prestaflow.io. |
PRESTAFLOW_PASSED |
Number of passing tests. |
PRESTAFLOW_FAILED |
Number of failing tests. |
PRESTAFLOW_SKIPPED |
Number of skipped tests. |
PRESTAFLOW_TOTAL |
Total number of tests. |
PRESTAFLOW_DURATION_MS |
Total execution duration in milliseconds. |
PRESTAFLOW_STATUS |
success if failed==0, else failure. |
Example downstream consumption:
1notify:2 stage: deploy3 needs:4 - job: prestaflow5 artifacts: true6 script:7 - echo "Report at $PRESTAFLOW_REPORT_URL ($PRESTAFLOW_STATUS)"
#MR comments
On merge-request pipelines, the component posts (or updates) a summary note
listing the pass/fail/skipped counts, the run duration and a link to the
report on prestaflow.io. The note is tagged with a hidden marker
(<!-- prestaflow-run:<projectKey> -->) so subsequent pushes update the
existing note in place rather than appending a new one.
CI_JOB_TOKEN cannot create merge-request notes, so you must expose a
project or personal access token with api scope as the GITLAB_TOKEN
CI/CD variable. Without it, the component logs a warning and skips the
comment step (never fails the job).
#Script bundling
GitLab CI Components ship YAML only — they do not copy the component
repository's files into the runner's workspace. To reach scripts/*.sh at
runtime, the template's before_script clones the component's source into
$CI_PROJECT_DIR/.prestaflow-component/ (idempotent — skipped if present,
which is the case when the consumer already cloned in their own
before_script per Option B). The scripts are then invoked as
bash .prestaflow-component/scripts/<name>.sh.
The clone URL and ref default to this GitHub repo at main; override with
the component_repo / component_ref inputs if you fork or pin.
#Publishing / mirroring
To publish the component on gitlab.com's CI/CD Catalog:
1git clone --mirror https://github.com/PrestaFlow/gitlab-component.git2cd gitlab-component.git3git remote add gitlab https://gitlab.com/prestaflow/ci.git4git push --mirror gitlab
Then in the gitlab.com project, tag a release (v0.1.0, v0.2.0, …) and
enable "CI/CD Catalog project" in Settings → General. Consumers can then
use the canonical component: shorthand.
#Behavior differences vs the GitHub Action
The port is behavior-for-behavior with two small platform-imposed changes:
- PR comment auth. The GitHub Action uses the auto-injected
GITHUB_TOKEN. GitLab'sCI_JOB_TOKENcannot create merge-request notes, so this component requires an explicitGITLAB_TOKENCI variable. - Outputs. The GitHub Action sets step outputs via
core.setOutput. On GitLab, outputs are conveyed through adotenvartifact (prestaflow.env). Downstream jobs consume them by declaringneeds: [{ job: prestaflow, artifacts: true }].
Everything else — inputs, Flashlight boot, visual round-trip, results
upload, comment marker format (<!-- prestaflow-run:<projectKey> -->) —
matches the GitHub Action.
#Troubleshooting
- MR comment not posted —
CI_JOB_TOKENcannot create MR notes. Expose a project or personal access token withapiscope as theGITLAB_TOKENCI variable. component:shorthand fails to resolve — the CI/CD Catalog only resolves against$CI_SERVER_FQDN. Either mirror to gitlab.com (Option A) or use the localinclude:clone approach (Option B).- Scripts not found at runtime — the template's
before_scriptclones the component into.prestaflow-component/. If you overridebefore_script, chain to the component's clone step or the scripts will be missing. - Flashlight boot fails — the runner must expose
docker:dindas a service, and the job must have Docker available. See the GitHub Action guide for image-and-mount compatibility rules — they apply here as well.
#Links
- Component repository: PrestaFlow/gitlab-component
- Companion GitHub Action: PrestaFlow/github-action
- PrestaShop Flashlight: PrestaShop/prestashop-flashlight