GitLab CI/CD Component


#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.

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:

Copied!
1include:
2 - component: gitlab.com/prestaflow/ci/prestaflow@v0.1.0
3 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:

Copied!
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.yml
10 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:

Copied!
1include:
2 - component: gitlab.com/prestaflow/ci/prestaflow@v0.1.0
3 inputs:
4 token: $PRESTAFLOW_TOKEN
5 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

Copied!
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:

Copied!
1notify:
2 stage: deploy
3 needs:
4 - job: prestaflow
5 artifacts: true
6 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:

Copied!
1git clone --mirror https://github.com/PrestaFlow/gitlab-component.git
2cd gitlab-component.git
3git remote add gitlab https://gitlab.com/prestaflow/ci.git
4git 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:

  1. PR comment auth. The GitHub Action uses the auto-injected GITHUB_TOKEN. GitLab's CI_JOB_TOKEN cannot create merge-request notes, so this component requires an explicit GITLAB_TOKEN CI variable.
  2. Outputs. The GitHub Action sets step outputs via core.setOutput. On GitLab, outputs are conveyed through a dotenv artifact (prestaflow.env). Downstream jobs consume them by declaring needs: [{ 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_TOKEN cannot create MR notes. Expose a project or personal access token with api scope as the GITLAB_TOKEN CI 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 local include: clone approach (Option B).
  • Scripts not found at runtime — the template's before_script clones the component into .prestaflow-component/. If you override before_script, chain to the component's clone step or the scripts will be missing.
  • Flashlight boot fails — the runner must expose docker:dind as 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.