> ## Documentation Index > Fetch the complete documentation index at: https://docs.cekura.ai/llms.txt > Use this file to discover all available pages before exploring further. # GitLab CI/CD Tutorial > Learn how to automatically test your agents in GitLab pipelines with the Cekura CI/CD component export const CopyPageButton = () => { if (typeof window !== 'undefined') { setTimeout(function () { if (document.getElementById('ck-tools')) return; var anchor = document.getElementById('content-area') || document.querySelector('.mdx-content'); if (!anchor) return; if (!document.getElementById('ck-style')) { var s = document.createElement('style'); s.id = 'ck-style'; s.textContent = '#ck-tools{position:absolute;top:6px;right:0;z-index:100;font-family:inherit;}' + '.ck-row{display:inline-flex;align-items:stretch;border:1px solid rgba(0,0,0,0.15);border-radius:8px;overflow:hidden;background:#fff;}' + ':root.dark .ck-row{background:rgba(255,255,255,0.06);border-color:rgba(255,255,255,0.12);}' + '.ck-btn{padding:5px 12px;border:none;background:none;cursor:pointer;font-size:13px;font-weight:500;font-family:inherit;color:#374151;}' + ':root.dark .ck-btn{color:#d1d5db;}' + '.ck-btn:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-btn:hover{background:rgba(255,255,255,0.06);}' + '.ck-chevron{padding:5px 8px;border:none;background:none;cursor:pointer;font-size:14px;font-family:inherit;color:#374151;}' + ':root.dark .ck-chevron{color:#d1d5db;}' + '.ck-chevron:hover{background:rgba(0,0,0,0.04);}' + ':root.dark .ck-chevron:hover{background:rgba(255,255,255,0.06);}' + '.ck-divider{width:1px;background:rgba(0,0,0,0.12);flex-shrink:0;}' + ':root.dark .ck-divider{background:rgba(255,255,255,0.12);}' + '.ck-dd{position:absolute;top:calc(100% + 4px);right:0;min-width:180px;background:#fff;border:1px solid rgba(0,0,0,0.12);border-radius:8px;box-shadow:0 4px 12px rgba(0,0,0,0.1);padding:4px;display:none;z-index:200;}' + ':root.dark .ck-dd{background:#1f2937;border-color:rgba(255,255,255,0.1);box-shadow:0 4px 16px rgba(0,0,0,0.35);}' + '.ck-item{display:block;width:100%;padding:7px 12px;border:none;background:none;border-radius:6px;cursor:pointer;font-size:13px;font-family:inherit;text-align:left;color:#374151;}' + ':root.dark .ck-item{color:#d1d5db;}' + '.ck-item:hover{background:rgba(0,0,0,0.05);}' + ':root.dark .ck-item:hover{background:rgba(255,255,255,0.07);}'; document.head.appendChild(s); } var wrap = document.createElement('div'); wrap.id = 'ck-tools'; var row = document.createElement('div'); row.className = 'ck-row'; var mainBtn = document.createElement('button'); mainBtn.className = 'ck-btn'; mainBtn.textContent = 'Copy page'; var divider = document.createElement('span'); divider.className = 'ck-divider'; var chevron = document.createElement('button'); chevron.className = 'ck-chevron'; chevron.textContent = '▾'; var dd = document.createElement('div'); dd.className = 'ck-dd'; function closeDD() { dd.style.display = 'none'; } function openDD() { dd.style.display = 'block'; } chevron.onclick = function (e) { e.stopPropagation(); if (dd.style.display === 'block') { closeDD(); } else { openDD(); } }; document.addEventListener('click', function (e) { if (!e.target.closest('#ck-tools')) { closeDD(); } }); document.addEventListener('keydown', function (e) { if (e.key === 'Escape') { closeDD(); } }); function makeItem(label, fn) { var b = document.createElement('button'); b.className = 'ck-item'; b.textContent = label; b.onclick = function () { fn(); closeDD(); }; return b; } function getMarkdown() { var walk = function (node) { if (!node) return ''; if (node.nodeType === 3) return node.textContent || ''; if (node.nodeType !== 1) return ''; var tag = node.tagName.toLowerCase(); var skip = ['script', 'style', 'svg', 'noscript', 'button', 'iframe']; if (skip.indexOf(tag) !== -1) return ''; if (node.id === 'ck-tools') return ''; var ch = Array.from(node.childNodes).map(walk).join(''); if (tag === 'h1') return '\n# ' + ch.trim() + '\n\n'; if (tag === 'h2') return '\n## ' + ch.trim() + '\n\n'; if (tag === 'h3') return '\n### ' + ch.trim() + '\n\n'; if (tag === 'p') return '\n' + ch.trim() + '\n\n'; if (tag === 'pre') return '\n```\n' + node.textContent.trim() + '\n```\n\n'; if (tag === 'li') return '- ' + ch.trim() + '\n'; if (tag === 'code') return '`' + ch.trim() + '`'; return ch; }; var content = document.querySelector('.mdx-content') || document.getElementById('content-area') || document.body; return walk(content).replace(/\n\n\n+/g, '\n\n').trim(); } function copyMd() { var md = getMarkdown(); navigator.clipboard.writeText(md).then(function () { mainBtn.textContent = 'Copied!'; setTimeout(function () { mainBtn.textContent = 'Copy page'; }, 2000); }); } function viewMd() { var md = getMarkdown(); var safe = md.split('&').join('&').split('<').join('<').split('>').join('>'); var html = '' + safe + ''; window.open(URL.createObjectURL(new Blob([html], { type: 'text/html' })), '_blank'); } function openClaude() { var prompt = 'Can you read this Cekura docs page ' + window.location.href + ' so I can ask you questions?'; window.open('https://claude.ai/new?q=' + encodeURIComponent(prompt), '_blank'); } mainBtn.onclick = copyMd; dd.appendChild(makeItem('Copy page', copyMd)); dd.appendChild(makeItem('View as Markdown', viewMd)); dd.appendChild(makeItem('Open in Claude', openClaude)); row.appendChild(mainBtn); row.appendChild(divider); row.appendChild(chevron); wrap.appendChild(row); wrap.appendChild(dd); anchor.style.position = 'relative'; anchor.insertBefore(wrap, anchor.firstChild); }, 50); } return null; }; Automate your agent testing with the [Cekura GitLab CI/CD component](https://gitlab.com/cekura/cicd). This guide shows you how to run Cekura scenarios on every code change, merge request, or scheduled pipeline. The component starts a Cekura test, waits for it to finish, and reports the result through GitLab job logs, the **Tests** tab, job annotations, and downloadable artifacts. ## Before You Get Started Before setting up a pipeline, configure your agent and scenarios in the [Cekura dashboard](https://dashboard.cekura.ai). You need: * A Cekura API key * Scenarios selected by IDs, tags, or evaluator folder * A Cekura project ID when selecting an evaluator folder The agent ID is optional. If you omit it, Cekura infers the agent from the selected scenarios. ## Choose Which Scenarios to Run Run an exact set of scenarios using comma-separated IDs. ```yaml theme={null} scenario_ids: "101,202" ``` Run scenarios grouped by one or more comma-separated tags. ```yaml theme={null} tags: "smoke,release" ``` Run every scenario in a folder. A project ID is required, even when you provide an agent ID. ```yaml theme={null} folder_path: "Release checks" project_id: "1875" ``` Provide at least one selector. A folder cannot be combined with scenario IDs or tags. ## Step-by-Step Tutorial In your GitLab project, go to **Settings → CI/CD → Variables**, expand **Variables**, and select **Add variable**. Set the key to `CEKURA_API_KEY`, paste your Cekura API key as the value, and enable **Masked**. Enable **Protected** only when the Cekura job runs exclusively on protected branches or tags. Protected variables are not available to pipelines on unprotected refs. Never put your API key directly in `.gitlab-ci.yml`. Create or update `.gitlab-ci.yml` in the root of your repository: ```yaml theme={null} include: - component: gitlab.com/cekura/cicd/run@1.0.0 inputs: api_key: $CEKURA_API_KEY scenario_ids: "101,202" ``` Replace the scenario IDs with your own. You can use `tags` or `folder_path` instead. Commit and push `.gitlab-ci.yml`. By default, the generated `cekura-run` job runs whenever the pipeline is triggered. You can also go to **Build → Pipelines**, select **New pipeline**, choose a branch, and select **New pipeline** again to test it manually. Open the `cekura-run` job to see the result summary, failed-run details, and a shareable link to the full result in Cekura. GitLab also displays each scenario run in the pipeline's **Tests** tab. The job publishes Markdown and JSON summaries as artifacts and adds a direct Cekura result link to the job page. ## Run by Folder Use `folder_path` with `project_id` to run all scenarios in an evaluator folder: ```yaml theme={null} include: - component: gitlab.com/cekura/cicd/run@1.0.0 inputs: api_key: $CEKURA_API_KEY folder_path: "Release checks" project_id: "1875" ``` ## Configure Pipeline Triggers The component creates a job named `cekura-run`. Define that job again in your pipeline to add GitLab [`rules`](https://docs.gitlab.com/ci/yaml/#rules); GitLab merges your configuration with the included job. ```yaml theme={null} include: - component: gitlab.com/cekura/cicd/run@1.0.0 inputs: api_key: $CEKURA_API_KEY tags: "smoke" cekura-run: rules: - if: $CI_PIPELINE_SOURCE == "merge_request_event" - if: $CI_COMMIT_BRANCH == $CI_DEFAULT_BRANCH ``` ```yaml theme={null} include: - component: gitlab.com/cekura/cicd/run@1.0.0 inputs: api_key: $CEKURA_API_KEY tags: "smoke" cekura-run: rules: - when: manual ``` ```yaml theme={null} include: - component: gitlab.com/cekura/cicd/run@1.0.0 inputs: api_key: $CEKURA_API_KEY tags: "regression" cekura-run: rules: - if: $CI_PIPELINE_SOURCE == "schedule" ``` Create the schedule under **Build → Pipeline schedules** in your GitLab project. ## Component Inputs Only `api_key` and a scenario selector are needed for a typical run. Empty optional inputs are not sent to Cekura, so the API applies its defaults. | Input | Description | Required | Default | | ------------------- | ---------------------------------------------------------------------------------------- | ----------- | ----------------------- | | `api_key` | Cekura API key. Pass a masked CI/CD variable. | Yes | - | | `scenario_ids` | Comma-separated scenario IDs. | No\* | - | | `tags` | Comma-separated scenario tags. | No\* | - | | `folder_path` | Evaluator folder path. Requires `project_id`, even when `agent_id` is provided. | No\* | - | | `project_id` | Cekura project ID used with `folder_path`. | With folder | - | | `agent_id` | Agent ID override. Otherwise inferred from the selected scenarios. | No | - | | `phone_number` | Outbound phone number used for testing. | No | - | | `agent_number` | Number on which the agent under test receives calls. | No | - | | `name` | Name for the Cekura test result. | No | - | | `api_url` | Cekura API base URL. | No | `https://api.cekura.ai` | | `frequency` | Number of times to run each scenario. | No | `1` | | `personality_ids` | Comma-separated personality ID overrides. | No | - | | `test_profile_ids` | Comma-separated test profile ID overrides. | No | - | | `mode` | `same_number` or `different_numbers`. | No | API default | | `concurrency_limit` | Maximum number of parallel calls. | No | API default | | `mock_tool_names` | Comma-separated tools to mock. Use `[]` to mock none; omit to mock all configured tools. | No | API default | | `timeout` | Maximum time to wait for completion, in seconds. | No | `3600` | | `stage` | Pipeline stage for the generated job. | No | `test` | \*Provide at least one of `scenario_ids`, `tags`, or `folder_path`. ### Example with Optional Inputs ```yaml theme={null} include: - component: gitlab.com/cekura/cicd/run@1.0.0 inputs: api_key: $CEKURA_API_KEY scenario_ids: "101,202" agent_id: "42" name: "Release candidate" frequency: 2 concurrency_limit: "5" timeout: 7200 ``` ## Use the Result in Another Job The component publishes `RESULT_ID` and `RESULT_URL` in a GitLab dotenv report. A downstream job can use them by downloading the `cekura-run` artifacts: ```yaml theme={null} publish-cekura-result: stage: deploy needs: - job: cekura-run artifacts: true script: - echo "Cekura result: ${RESULT_URL} (${RESULT_ID})" ``` ## Troubleshooting Check that `CEKURA_API_KEY` is defined under **Settings → CI/CD → Variables** and is spelled exactly the same in `.gitlab-ci.yml`. If the variable is protected, the pipeline must run on a protected branch or tag. Otherwise, clear the **Protected** option or change where the job runs. Confirm that the component reference is exactly `gitlab.com/cekura/cicd/run@1.0.0` and that `inputs` is nested under the component entry. Use **Build → Pipeline editor → Validate** in GitLab to validate the complete configuration. Provide `scenario_ids`, `tags`, or `folder_path`. When using a folder, also provide `project_id`, and do not combine the folder with IDs or tags. Open the `cekura-run` log for failure reasons and individual failed-run details. Follow the **View full results in Cekura** link for transcripts, evaluations, and the AI-generated analysis.