Skip to content

CI Integration RU

Pavel Erokhin edited this page Nov 16, 2026 · 2 revisions

English version

Место ctxray — в CI: тогда каждый merge request показывает, грузят ли ИИ-харнессы нужные правила, не вырос ли контекст и не нарушена ли политика. Здесь описаны GitHub Actions, GitLab CI и любой другой CI, который умеет запускать контейнер или shell-скрипт.

Каждый push запускает ctxray test, слои L1–L5 на mock-модели. Pull request проигрывает записанные ответы для L6 и L7 и сравнивает контекст с базовой веткой. Ответы записываются один раз на настоящей модели и коммитятся. Еженедельная задача гоняет L6 на настоящей модели с бюджетом. Каждая задача пишет отчёты и сводку.

Перед началом закоммитьте два файла: конфиг и ctxray.lock. Lock-файл закрепляет сборки харнессов, которые запускает CI, и без него в CI падает каждый тест начиная с L4 (почему — на странице Harnesses).

GitHub Actions

Action MairwunNx/ctxray-action ставит ctxray, кеширует харнессы из ctxray.lock и запускает ctxray test:

- uses: actions/checkout@v7
- uses: MairwunNx/ctxray-action@v0

@v0 следует за новейшим релизом 0.x. Закрепите точный тег, например @v0.1.0, если CI должен меняться только по вашему решению.

Входные параметры

Параметр По умолчанию Что делает
version версия самого action Версия ctxray, например 0.1.0
args test Что запустить, аргументы для ctxray: test --layer L1-L3, inspect, diff --base origin/master
working-directory . Папка проекта, где лежит ctxray.lock
cache true Кешировать между запусками харнессы из ctxray.lock
download-base GitHub Releases Где лежат релизы, для зеркала. То же, что CTXRAY_DOWNLOAD_BASE в install.sh

Action делит args по пробелам, поэтому один аргумент не может содержать пробел. Такие значения передавайте через конфиг или переменную окружения.

Action работает на раннерах Linux, macOS и Windows, x64 и arm64. Он ставит ctxray через install.sh (на Windows — install.ps1) во временную папку раннера и добавляет её в PATH, так что следующие шаги тоже могут вызывать ctxray.

Тесты на каждый push

name: ctxray

on:
  push:
  pull_request:

jobs:
  ctxray:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: MairwunNx/ctxray-action@v0
      - uses: actions/upload-artifact@v7
        if: always()
        with:
          name: ctxray-report
          path: .ctxray/report

В CI ctxray пишет вывод в консоль и отчёты JSON, JUnit, Markdown и HTML в .ctxray/report/. На GitHub он ещё и дописывает сводку в Markdown на страницу итогов job, так что результат видно без лога. Шаг с артефактом сохраняет HTML-отчёт для тех, кому нужны подробности.

Что меняет pull request

ctxray diff сравнивает, что каждый харнесс загружает в pull request и что загружал в базовой ветке. Ему нужна история базовой ветки, поэтому делайте checkout с fetch-depth: 0:

name: ctxray diff

on: pull_request

jobs:
  diff:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
        with:
          fetch-depth: 0
      - uses: MairwunNx/ctxray-action@v0
        with:
          args: diff --base origin/${{ github.base_ref }}

ctxray diff только сообщает: он выходит с кодом 0, что бы ни поменялось. Чтобы то же сравнение попало в сводку job и в HTML-отчёт рядом с результатами тестов, запускайте тесты с --base:

      - uses: MairwunNx/ctxray-action@v0
        with:
          args: test --base origin/${{ github.base_ref }}

Настоящие модели по расписанию

L6 Activate много раз отправляет промпты настоящей модели, а это стоит денег. Запускайте его по расписанию с ключом из секретов репозитория и ограничьте траты флагом --budget в долларах США:

name: ctxray activation

on:
  schedule:
    - cron: "0 4 * * 1"
  workflow_dispatch:

jobs:
  activation:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: MairwunNx/ctxray-action@v0
        with:
          args: test --layer L6 --backend real --budget 5
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}

Когда бюджет исчерпан, ещё не начатые тесты пропускаются с причиной «бюджет исчерпан», и одно это прогон не валит. Сам харнесс ключа не видит: его добавляет прокси ctxray по пути к модели. Какая переменная обслуживает какого провайдера и как ходить через шлюз — на странице Enterprise.

Воспроизведение на каждом pull request

Запишите ответы модели один раз с --record, закоммитьте кассеты, и каждый pull request будет воспроизводить их бесплатно. Как записывать и где лежат кассеты, объясняет Writing Tests.

ctxray test --layer L6-L7 --backend real --record
name: ctxray

on: pull_request

jobs:
  ctxray:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v7
      - uses: MairwunNx/ctxray-action@v0
        with:
          args: test --backend replay

Воспроизведению не нужны ни ключ, ни сеть: L1–L5 идут как обычно, а L6–L7 проигрывают записанные ответы.

GitLab CI

В каждом релизе есть шаблон ctxray.gitlab-ci.yml. Подключите его и унаследуйте скрытый job .ctxray:

include:
  - remote: https://github.com/MairwunNx/ctxray/releases/latest/download/ctxray.gitlab-ci.yml

ctxray:
  extends: .ctxray

latest следует за каждым релизом. Чтобы закрепить один, укажите его тег: https://github.com/MairwunNx/ctxray/releases/download/v0.1.0/ctxray.gitlab-ci.yml. В закрытом контуре держите копию шаблона в своём проекте и подключайте оттуда:

include:
  - project: platform/ci-templates
    ref: main
    file: ctxray.gitlab-ci.yml

ctxray:
  extends: .ctxray

Что делает шаблон

Job .ctxray запускает ctxray test $CTXRAY_ARGS в образе ghcr.io/mairwunnx/ctxray:<version>-runtime, где есть ctxray, git и Node. Он сохраняет .ctxray/report/ как артефакт, даже если job упал, и отдаёт junit.xml в GitLab как JUnit-отчёт. GitLab показывает каждый упавший тест в сводке тестов merge request.

Переменная По умолчанию Что делает
CTXRAY_IMAGE ghcr.io/mairwunnx/ctxray:<version>-runtime Образ, в котором идёт job. Укажите зеркало в своём реестре или образ с харнессами внутри
CTXRAY_ARGS пусто Дополнительные аргументы ctxray test, например --layer L1-L3
CTXRAY_CACHE_DIR $CI_PROJECT_DIR/.ctxray-cache Кеш харнессов. GitLab кеширует только внутри папки проекта

Job кеширует .ctxray-cache/ с ключом от ctxray.lock, так что новый lock-файл начинает новый кеш. .ctxray-cache/ и .ctxray/ ctxray никогда не считает файлами проекта, поэтому сборки харнессов из кеша не попадают ни в L1 lint, ни в копию проекта, на которой запускается L4. Добавить .ctxray-cache/ в .gitignore всё же стоит, если не хотите видеть его в git status.

Merge request

Чтобы сравнить с целевой веткой merge request, скачайте всю историю и передайте merge base:

ctxray:
  extends: .ctxray
  rules:
    - if: $CI_PIPELINE_SOURCE == "merge_request_event"
  variables:
    GIT_DEPTH: "0"
    CTXRAY_ARGS: --base $CI_MERGE_REQUEST_DIFF_BASE_SHA

Настоящие модели по расписанию

Сохраните ключ как masked-переменную CI/CD, а job пусть идёт только в пайплайнах по расписанию:

ctxray-activation:
  extends: .ctxray
  rules:
    - if: $CI_PIPELINE_SOURCE == "schedule"
  variables:
    CTXRAY_ARGS: --layer L6 --backend real --budget 5

Любой другой CI

Везде работают два способа: Docker-образы или install.sh.

Образ. Запускайте job в ghcr.io/mairwunnx/ctxray:<version>-runtime для L4 и выше или в ghcr.io/mairwunnx/ctxray:<version>, если нужны только L1–L3. Entrypoint образа — ctxray, поэтому сбросьте его там, где CI выполняет скрипт внутри контейнера. Теги перечислены в Getting Started.

Скрипт. Закрепите версию, чтобы каждый запуск ставил одну и ту же сборку:

curl -fsSL https://github.com/MairwunNx/ctxray/releases/download/v0.1.0/install.sh | CTXRAY_VERSION=0.1.0 sh
export PATH="$HOME/.local/bin:$PATH"
ctxray test

Дальше сделайте то, что за вас делают action и шаблон:

  1. Кешируйте папку, которую печатает ctxray cache dir, с ключом от хеша ctxray.lock.
  2. Сохраняйте .ctxray/report/ как артефакт, а .ctxray/report/junit.xml отдайте в просмотр тестов вашего CI.
  3. Убедитесь, что CI задаёт CI, или передайте --ci (ниже).

Что меняется в CI

ctxray считает запуск запуском в CI, когда CI, GITLAB_CI или GITHUB_ACTIONS заданы и не равны пустой строке, 0 или false. CI=false выключает режим CI вручную.

Локально В CI
Вывод живой вывод в терминале простые строки, которые сохранит лог
Репортеры console console, json, junit, markdown, html
ctxray.lock о расхождении с конфигом ctxray только сообщает --frozen: расхождение валит прогон
Сводка job на GitHub — сводка в Markdown дописывается, если задан GITHUB_STEP_SUMMARY

Репортеры CI действуют, только пока конфиг не задаёт reporters, а --reporter перекрывает и то и другое. Каждый файл описан на странице Reporters and Reports.

Флаг --ci включает всё это на любой машине, --frozen тоже. Передайте его, если ваш CI ни одну из этих переменных не задаёт.

Кеш харнессов

Харнессы — самая медленная часть холодного запуска: Claude Code, Codex и остальные вместе весят сотни мегабайт. ctxray ставит закреплённые в ctxray.lock сборки в свой кеш при первом использовании и дальше берёт их оттуда. ctxray cache dir печатает папку — ровно то, что нужно шагу кеша в CI:

- id: harness-cache
  run: echo "dir=$(ctxray cache dir)" >> "$GITHUB_OUTPUT"
- uses: actions/cache@v6
  with:
    path: ${{ steps.harness-cache.outputs.dir }}
    key: ctxray-${{ runner.os }}-${{ runner.arch }}-${{ hashFiles('ctxray.lock') }}
- run: ctxray harness install

Action делает именно это, когда cache равен true. Отдельный шаг ctxray harness install необязателен: ctxray test тоже ставит харнессы при первом использовании, но так загрузка видна отдельно от тестов. Папки кеша и CTXRAY_CACHE_DIRS описаны на странице Harnesses.

Готовый образ с харнессами

Раннеру, которому нельзя ходить в npm, или пайплайну, который не должен ждать загрузок, нужны харнессы прямо в образе. Для этого в каждом релизе есть harnesses.Dockerfile. Положите его в проект и соберите там:

docker build -f harnesses.Dockerfile -t registry.example.com/ci/ctxray .

Файл начинается с ghcr.io/mairwunnx/ctxray:<version>-runtime, копирует ctxray.config.ts и ctxray.lock и запускает ctxray harness install --frozen в /opt/ctxray/harnesses, которую указывает в CTXRAY_CACHE_DIRS. Если ваш конфиг — файл .jsonc или расширяет другие файлы, поправьте строку COPY. Харнессы приходят из вашего реестра по вашим лицензиям: собственные образы ctxray их никогда не содержат.

Пересобирайте образ при каждом изменении ctxray.lock. Затем направьте на него CI: CTXRAY_IMAGE в GitLab, container: в GitHub, образ job в остальных.

Коды выхода

Скрипты и пайплайны могут ветвиться по этим числам, и от релиза к релизу они не меняются:

Код Значение
0 Всё прошло
1 Упал тест или проверка
2 Неизвестная команда, флаг или аргумент либо неизвестная ревизия в --base
3 Конфига нет или он неверный
4 Подвели харнесс, сеть или файловая система: ctxray doctor нашёл ошибку, ctxray harness install не смог установить или команду, которой нужна сеть, запустили офлайн
5 Ошибка в ctxray. Сообщение ведёт на трекер задач
130 Ctrl-C или SIGINT

L4 и выше нужна песочница

Начиная с L4, ctxray запускает настоящий харнесс на копии проекта. В headless-режиме харнесс без спроса запускает MCP-серверы и хуки проекта, то есть выполняет код проекта. На macOS ctxray ограничивает запись прогона через sandbox-exec. В Linux и Windows такой песочницы нет: там песочница — контейнер CI или раннер, который выбрасывают после job.

Хостовые раннеры GitHub и GitLab одноразовые, так что с ними всё в порядке. На self-hosted раннере запускайте job в контейнере. ctxray doctor подскажет, какой случай у вашей машины: «На этой системе нет песочницы: запускайте L4 и выше в контейнере, как в CI».

Clone this wiki locally