Our review
Frames headless Claude Code execution inside the `ai` GitLab CI job of the Gramax repo: it describes the environment, the available tooling, and how to diagnose a failed pipeline before commenting on a merge request.
Strengths
- Precisely documents the runtime context (workspace layout, product repo, GitLab host, CI variables) so the agent orients itself immediately
- Provides exact `glab` commands to list failed jobs and read their traces, plus the method to map an error back to a file and line in the diff
- Enforces a useful review discipline: merge-request checklist as a hard gate, inline comments over a single dump, focus on correctness and security over style
- Carries review state across runs through `AI_CONTEXT_DIR`, `AI_REVIEW_MODE` and the previously reviewed SHA
Limitations
- Tightly coupled to an internal instance (`gitlab.ics-it.ru`, project `ics/doc-reader` id 155) and pre-provisioned secrets, so it is not portable as-is
- Assumes a specific CI job setup (bot token, GitLab cache keyed by MR IID, image containing glab/gh/bun); missing pieces break the workflow
- The supplied SKILL.md is truncated in the persistent-state section, which stays partly unspecified
Use it when an agent runs non-interactively in the Gramax `ai` CI job and must diagnose a pipeline or produce a merge request review.
Avoid it in an interactive local session or on a different repository/GitLab host, where the described environment and tokens do not apply.
Security analysis
CautionNo destructive, exfiltration, or obfuscated behavior: it is a straightforward CI operating manual using glab/gh/git/bun for their intended purposes. The concern is scope — it grants an autonomous agent authenticated write access (commit, MR, comment) to a live GitLab project, which is powerful but appropriate for the stated CI review use case. Hence caution rather than safe or risky.
- •Skill operates with pre-authenticated GitLab tokens (GITLAB_TOKEN, GITLAB_CLAUDE_ACCESS_TOKEN) and instructs the agent to post MR comments, open MRs, and commit fixes directly to the MR source branch — legitimate but write-capable actions against a remote repo.
- •Reads and acts on environment tokens; while it never instructs exfiltration, references to bot tokens mean a misbehaving model has authenticated write access to the GitLab project.
Examples
Look at the current pipeline jobs, find the ones that failed, and tell me exactly which file and line in this MR caused the break.Review MR !$CI_MERGE_REQUEST_IID — run the merge-request checklist first, then post inline comments only on real correctness or security issues.This is a continue run: diff the changes since AI_LAST_REVIEWED_SHA against AI_HEAD_SHA and comment only on what is new.name: ci
description: Use when running headless inside a GitLab CI job in the Gramax repo (the ai job). Establishes environment — repo checked out, glab/gh authenticated, what tools exist, how to read/post on GitLab, how to diagnose failed pipeline jobs. Triggers on "ci", "running in CI", "headless CI job", "ты в CI", "запущен в пайплайне".
Claude Code running headless in GitLab CI job for Gramax.
Environment
- Cwd = team workspace root (cloned fresh by
init.sh). Layout:gramax/— product repo, on MR source branch.cd gramaxfor code.docs/,board/— sibling repos (shallow)..claude/— workspace config + skills.
- GitLab host:
gitlab.ics-it.ru, projectics/doc-reader(id155). glabalready authed (GITLAB_HOST+GITLAB_TOKENset). Use for every GitLab op — read MRs, diffs, job logs, post notes.ghfor GitHub mirror (gram-ax/gramax, issues only).- Non-interactive: no prompts, no questions. Decide and act.
Tools in image
claude, glab, gh, git, bun, rg, fd, jq, uv/python3, openssh-client.
bun for JS/TS (bun run lint, bun run test <file>), rg/fd for search.
Current context
CI vars say where you are:
CI_MERGE_REQUEST_IID— MR (on MR pipeline).CI_MERGE_REQUEST_SOURCE_BRANCH_NAME/CI_MERGE_REQUEST_TARGET_BRANCH_NAME.CI_PIPELINE_ID— current pipeline.CI_PROJECT_ID(155),CI_PROJECT_PATH(ics/doc-reader),CI_SERVER_HOST.
CI vars omit MR body — pull live title/desc/diff with glab. Run from gramax/, or target -R ics/doc-reader:
glab mr view "$CI_MERGE_REQUEST_IID" -R ics/doc-reader
glab mr diff "$CI_MERGE_REQUEST_IID" -R ics/doc-reader
Diagnose failed pipeline jobs
Part of helping the dev: find which jobs failed and why, so you can propose a fix.
- List pipeline jobs, spot failed ones:
glab api "projects/155/pipelines/$CI_PIPELINE_ID/jobs?per_page=100" | jq -r '.[] | select(.status=="failed") | "\(.id)\t\(.name)\t\(.stage)"' - Read each failed job's log, find root cause (tail = error):
glab api "projects/155/jobs/<job-id>/trace" - Diagnose: lint break, test fail, type error, build error. Tie to the MR change that caused it.
- Tell dev concrete fix — file:line + what to change. If fix is small + safe, may commit it (attribution below).
Acting
- Reviews follow
merge-requestskill. Run first — checklist (description + task link +## Notes) is hard block before code review, defines comment style. - Prefer inline comments on exact lines (
merge-request→ REFERENCE.md → Inline comments), one thread = one finding, no status emoji. Summary MR note only for cross-file points not mapping to a line. Don't dump whole review in one note. - Output GitLab-flavored markdown. Reference files by path. Terse.
- Review: focus correctness bugs, security, clear simplifications. Skip style nits (Biome handles). Nothing material wrong → say so in one line.
- Attribution: commit or open MR → append the
Assisted-By: <model display name>footer (e.g.Assisted-By: Claude Opus 4.8). - Comment replies = bot. Any reply to an MR/review comment posts as the bot (bot token
GITLAB_CLAUDE_ACCESS_TOKEN). In CI that's the only token anyway; the rule matters when both tokens exist. - Conventions in
gramax/CLAUDE.md+ workspaceCLAUDE.md(cwd). Follow.
Persistent review context across runs
ai job persists context dir between runs on same MR (GitLab cache keyed by MR IID). CI script restores before start, saves after, exports:
AI_CONTEXT_DIR— abs path to persisted dir (always exists). Read/write state here.AI_REVIEW_MODE—fresh(first review) orcontinue(reviewed before).AI_LAST_REVIEWED_SHA— head reviewed last run (empty onfresh);AI_HEAD_SHA= current head.
State file: $AI_CONTEXT_DIR/review-state.md. Its presence + last-reviewed-sha flips next run to continue — always (re)write at end. Keep compact:
- Current head SHA + one-line MR summary.
- Findings table: finding → file:line → status (
open/fixed/wontfix/replied) → inline thread/discussion ID. - Open questions to author, waiting on.
- Latest MR note timestamp seen (detect new comments next run).
fresh mode
Full review. Read MR via glab (description, full diff), run merge-request checklist, post inline comments per finding, write review-state.md from scratch.
continue mode — resume, don't restart
- Read
$AI_CONTEXT_DIR/review-state.md— memory of prior review. - Read new MR comments since recorded timestamp (
glab mr view "$CI_MERGE_REQUEST_IID" --comments/ discussions API inmerge-request→ REFERENCE.md). Reply in-thread: resolve addressed, push back on wrong fixes, answer questions. - Review only new commits. Diff range, not whole MR:
git -C gramax diff "$AI_LAST_REVIEWED_SHA".."$AI_HEAD_SHA"(--statfirst to scope).AI_LAST_REVIEWED_SHA==AI_HEAD_SHA→ no new code, only process comments. Don't re-review unchanged code or re-post known findings. - Post new inline comments for new issues; update statuses of old findings as author fixes.
- Rewrite
review-state.md: bump head SHA + timestamp, merge new findings, update statuses.
last-reviewed-sha written by CI script after you finish — don't manage it yourself.
Incident Postmortem Writer
DevOps
Writes structured and blameless incident postmortem reports.
Runbook Creator
DevOps
Creates clear operational runbooks for common DevOps procedures.
Health Checks
DevOps
Implement health check endpoints for service readiness, liveness, and dependency monitoring.