Skip to content

Configure GitLab CI

Status: ✅ It's the most complete integration. The pipeline triggers on its own when an MR has the feature label, saves the results in a new MR, and comments the result on the original MR.

Value in qa-stack.yaml stack.pipeline_provider: gitlab
Entry file .gitlab-ci.yml
NEO files .gitlab/neo-ci-jobs/
How it's triggered Merge Request with the feature label
Image $CI_REGISTRY/lippia/products/neo/crowdar-engine-mvp:c4cd2740-playwright

1. What lippia-neo-ci-bootstrap generates

If the repository doesn't have .gitlab-ci.yml

File What it contains
.gitlab-ci.yml Only the include: pointing to the NEO manager
.gitlab/neo-ci-jobs/NeoCiManager.yml Stages, variables, shared blocks, and the publish-report job. It includes the three files below
.gitlab/neo-ci-jobs/FeatureNewEndToEnd.yml The feature-e2e job (feature-new-end-to-end plan)
.gitlab/neo-ci-jobs/QaReadStack.yml The qa-read-stack job (reads the paths from qa-stack.yaml)
.gitlab/neo-ci-jobs/UiSelectorRepair.yml The ui-selector-repair job (ui-selector-repair plan)

The generated .gitlab-ci.yml looks like this:

# lippia-neo: incluye los test jobs
include:
  - local: '.gitlab/neo-ci-jobs/NeoCiManager.yml'

The five files must be at those exact paths. If one is missing, GitLab can't find the include: and the pipeline doesn't start.

If the repository already has .gitlab-ci.yml

lippia-neo-ci-bootstrap doesn't replace it. It copies the .gitlab/neo-ci-jobs/ folder and adds only this to your .gitlab-ci.yml:

# lippia-neo: incluye los test jobs
include:
  - local: '.gitlab/neo-ci-jobs/NeoCiManager.yml'

If your file already had an include: block, the line is added to that list: GitLab allows only one include: per file.

If you already use a stage named NEO or report, or jobs with the same names (feature-e2e, publish-report…), check that they don't clash.


2. The jobs

Stage Job What it does When it runs
NEO feature-e2e Clones the skills, detects the framework and installs dependencies, writes .env.tests, runs the feature-new-end-to-end plan, and pushes the results to a new branch with its own MR On an MR with the feature label (when it's opened and on every push)
report publish-report Comments the result on the MR. It always runs, even if feature-e2e fails Same criteria as feature-e2e
NEO qa-read-stack Reads the paths from qa-stack.yaml and publishes them for the following jobs Push to the develop branch that changes files in src/components/ or src/pages/
NEO ui-selector-repair Runs the ui-selector-repair plan, which fixes test selectors based on the push diff Same criteria as qa-read-stack

Adjust the triggers to your project. qa-read-stack and ui-selector-repair assume the UI code is in src/components/ and src/pages/ and that the integration branch is called develop. If your repository uses a different structure or branch, change those rules in the generated files.

What happens with the results

If the plan finishes successfully and generated files (plans, tests, or reports in the qa-stack.yaml folders), feature-e2e:

  1. Creates the branch feature-new-end-to-end/<MR number> with those files.
  2. Opens a new MR targeting your MR's branch, titled "Neo: Results of feature-new-end-to-end plan for <your branch>".

That way you can review what NEO generated before adding it to your branch. If there were no changes, it leaves the message Nothing to persist.


3. Step by step

Step 1 — Generate the files

With qa-stack.yaml already created (pipeline_provider: gitlab), ask the assistant:

Generate the project's CI with lippia-neo-ci-bootstrap

Review the generated files and commit them.

Step 2 — Add the variables

In GitLab: Settings → CI/CD → Variables → Add variable.

Variable Type / options What it's for
ANTHROPIC_API_KEY Masked Claude models
OPENAI_API_KEY Masked OpenAI models, if the plan uses them (ui-selector-repair uses openai/gpt-5.4)
CROWDAR_CI_TOKEN Masked Commenting on the MR, and pushing the branch and opening the results MR
APP_USER Variable The app's test user
APP_PASSWORD Masked Test password
APP_BASE_URL Variable URL of the app under test

If your user stories come from Jira, add JIRA_URL, JIRA_USERNAME, JIRA_API_TOKEN (Masked), CONFLUENCE_URL, CONFLUENCE_USERNAME, and CONFLUENCE_API_TOKEN (Masked). If they come from Azure DevOps, add AZURE_DEVOPS_ORG_URL, AZURE_DEVOPS_AUTH_METHOD (= pat), AZURE_DEVOPS_PAT (Masked) and, optionally, AZURE_DEVOPS_DEFAULT_PROJECT. The values are the same as in Jira and Azure DevOps.

⚠️ Be careful with "Protect variable". A protected variable only reaches pipelines on protected branches or tags. Since feature-e2e runs in the pipeline of an MR from a feature branch, if you mark the variables as protected the job can't see them and fails because of empty credentials.

CROWDAR_CI_TOKEN: it must be able to comment on MRs, push a branch, and open an MR. For example, a Project access token with the api and write_repository scopes. If the target branch is protected against pushes, the results MR can't be created (the job reports it and keeps going).

You don't need to add credentials for the image or for cloning the skills: $CI_REGISTRY and $CI_JOB_TOKEN are used, because they're on the same Crowdar GitLab instance. Your project must have access to lippia/products/neo/crowdar-qa-skills and to the crowdar-engine-mvp registry.

Step 3 — Create the label

In GitLab: Manage → Labels → New label → name feature.

The rule looks for the text feature inside the MR's labels, so a label like feature-request also triggers it.

Step 4 — Test it

  1. Open a test MR and add the feature label.
  2. In the MR's Pipelines tab you should see feature-e2e and publish-report.
  3. When it finishes, the MR gets a comment with the result and, if files were generated, the results MR appears.

4. Common problems (and what to do)

What you see Why it may happen What to do
The pipeline doesn't run when you add the label The pipeline isn't a merge request pipeline, or the label doesn't contain feature Check the label; remove it and add it again, or make a new push
YAML error: include not found One of the files in .gitlab/neo-ci-jobs/ is missing or was renamed Regenerate with lippia-neo-ci-bootstrap and commit all five files
YAML error in ui-selector-repair: unknown .setup-test-framework reference UiSelectorRepair.yml references a .setup-test-framework block that isn't defined in NeoCiManager.yml It's a known issue with the template. If you don't use ui-selector-repair, remove its include from NeoCiManager.yml; if you do use it, let the NEO team know
The crowdar-engine-mvp image can't be downloaded The project doesn't have access to the Crowdar registry Request access to the crowdar-engine-mvp project
The skills git clone fails The project's CI_JOB_TOKEN doesn't have access to crowdar-qa-skills Ask for your project to be added to the token allowlist of the skills repository
The credentials arrive empty Variables marked as Protected in an MR pipeline Uncheck Protect variable
could not push/open the report MR CROWDAR_CI_TOKEN without permissions, or protected branch Check the token's permissions
could not post the MR comment CROWDAR_CI_TOKEN without the api scope Check the token
The job reinstalls everything on every run The runner's distributed cache isn't available It's not an error: it's slower, but it works the same