Letting an agent read GitLab CI results

This guide explains how you (or a Cursor agent) can inspect GitLab pipeline results for libesys/esysdox-ops without guessing from local runs alone.

The GitLab project is private, so unauthenticated API calls return “project not found.” You need either a token on your machine or manual sharing of logs.

Related:

• Pipelines and jobs: gitlab-ci.md
• First push: gitlab-getting-started.md
• SSH remotes: gitlab-ssh-keys.md

What agents can and cannot do today

Capability	Agent (Cursor)	You
Run git push / git fetch via gitlab-ai	Yes, if SSH is configured on your PC	Yes
See GitLab UI (Pipelines page)	No, unless you share it	Yes
Call GitLab API without a token	No (private project)	Yes (browser)
Run glab / curl with your token	Yes, in your shell	Yes

Agents run commands on your workstation. They do not get a separate GitLab login. Any integration uses your credentials from the environment or from tools you install locally.

Option 1 — Paste or screenshot (no setup)

Fastest when something fails:

1. Open Build → Pipelines → failed pipeline → failed job.
2. Copy the job log (last ~50 lines often enough) or the pipeline URL.
3. Paste into the chat, or attach a screenshot.

Also useful: job name (ruff, unit, integration), commit SHA, and branch.

Option 2 — GitLab CLI (glab) (recommended)

glab talks to GitLab with your account or a token. After you authenticate once, an agent can run read-only commands in the repo directory.

Install

• Windows: winget install glab.glab or download from GitLab releases.
• Linux/macOS: see glab install docs.

Authenticate (one time)

glab auth login

Follow the browser or token flow for gitlab.com (or your self-managed host).

Alternatively, set a token in your user environment (never commit it):

# PowerShell — session or user env var
$env:GITLAB_TOKEN = "glpat-xxxxxxxx"
glab auth status

Create the token under Preferences → Access tokens or Project → Access tokens with at least:

Scope	Purpose
read_api	List pipelines and jobs, fetch job trace

Commands an agent can run

From the repository root (project libesys/esysdox-ops):

# Recent pipelines on the current branch / default branch
glab ci list

# Status of the latest pipeline
glab ci status

# Open detailed view (terminal UI)
glab ci view

# Trace/log for a job (example job name from .gitlab-ci.yml)
glab ci trace ruff
glab ci trace unit
glab ci trace integration

Set the default project if prompted, or per command:

glab ci status -R libesys/esysdox-ops

What to ask the agent

Examples:

• “List the last three GitLab pipelines with glab.”
• “Show the log for the failed integration job on the latest pipeline.”
• “Confirm the latest pipeline on master passed all jobs.”

Option 3 — GitLab REST API + curl

Same idea as glab, without installing glab. Use a private token in an environment variable:

$headers = @{ "PRIVATE-TOKEN" = $env:GITLAB_TOKEN }
$project = "libesys%2Fesysdox-ops"
curl.exe --ssl-no-revoke -H "PRIVATE-TOKEN: $env:GITLAB_TOKEN" `
  "https://gitlab.com/api/v4/projects/$project/pipelines?per_page=5"

Useful endpoints:

Endpoint	Returns
GET /projects/:id/pipelines	Recent pipelines
GET /projects/:id/pipelines/:id	One pipeline (status)
GET /projects/:id/pipelines/:id/jobs	Jobs in a pipeline
GET /projects/:id/jobs/:job_id/trace	Job log text

On Windows, curl.exe --ssl-no-revoke avoids some certificate revocation errors in corporate environments.

Option 4 — Cursor GitLab integration / MCP

If your Cursor installation supports a GitLab MCP server or GitLab integration:

1. Connect the GitLab account or token in Cursor Settings (MCP / Integrations).
2. Grant read_api (and project access to libesys/esysdox-ops).
3. Ask the agent to use that integration for pipeline status.

Availability depends on your Cursor version and org policy; it is not assumed in every session. If no GitLab tool appears in the agent’s tool list, use glab or paste logs instead.

Option 5 — Reproduce CI locally (verification, not live status)

Agents can mirror GitLab jobs without API access:

pip install -e ".[dev]"
ruff check src tests scripts/pre_commit scripts/gitlint_rules.py
ruff format --check src tests scripts/pre_commit scripts/gitlint_rules.py
python -m pytest -q --cov=edox_ops
bash tests/integration/run_docker.sh   # Linux; Windows: .\test.ps1

This confirms the same commands as .gitlab-ci.yml on the current tree; it does not prove GitLab’s pipeline UI is green unless the same commit was pushed.

Security practices

Do	Don’t
Store tokens in user env vars or glab auth	Commit GITLAB_TOKEN or .env with secrets
Use minimal scope (read_api for inspection)	Paste tokens into chat or issues
Revoke tokens when a machine is retired	Share one personal token in the repo README
Use project access tokens for automation	Give api / write_repository unless needed

SSH keys for git push (see gitlab-ssh-keys.md) are separate from API tokens for reading CI logs.

Quick checklist for “agent can check CI”

• GitLab project exists: libesys/esysdox-ops
• glab installed and glab auth status OK, or GITLAB_TOKEN set
• Agent told to use -R libesys/esysdox-ops or default project configured
• On failure: glab ci trace <job> or paste job log in chat

Mapping to .gitlab-ci.yml jobs

GitLab job	Stage	Local equivalent
ruff	lint	ruff check + ruff format --check
unit	test	pytest -q --cov=edox_ops (coverage % + Cobertura in GitLab UI)
integration	integration	bash tests/integration/run_docker.sh

When an agent reports “CI passed,” ideally it has either glab/API confirmation for commit 1dae36a (or newer) on master, or you confirmed it in the GitLab UI and the agent verified the same SHA with git fetch gitlab.