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
NEOorreport, 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-stackandui-selector-repairassume the UI code is insrc/components/andsrc/pages/and that the integration branch is calleddevelop. If your repository uses a different structure or branch, change thoserulesin 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:
- Creates the branch
feature-new-end-to-end/<MR number>with those files. - 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-e2eruns 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_REGISTRYand$CI_JOB_TOKENare used, because they're on the same Crowdar GitLab instance. Your project must have access tolippia/products/neo/crowdar-qa-skillsand to thecrowdar-engine-mvpregistry.
Step 3 — Create the label
In GitLab: Manage → Labels → New label → name feature.
The rule looks for the text
featureinside the MR's labels, so a label likefeature-requestalso triggers it.
Step 4 — Test it
- Open a test MR and add the
featurelabel. - In the MR's Pipelines tab you should see
feature-e2eandpublish-report. - 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 |