Repository navigation
CI Integration RU
Место ctxray — в CI: тогда каждый merge request показывает, грузят ли ИИ-харнессы нужные правила, не вырос ли контекст и не нарушена ли политика. Здесь описаны GitHub Actions, GitLab CI и любой другой CI, который умеет запускать контейнер или shell-скрипт.
Перед началом закоммитьте два файла: конфиг и ctxray.lock. Lock-файл закрепляет сборки харнессов, которые запускает CI, и без него в CI падает каждый тест начиная с L4 (почему — на странице Harnesses).
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.
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-отчёт для тех, кому нужны подробности.
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.
Запишите ответы модели один раз с --record, закоммитьте кассеты, и каждый pull request будет воспроизводить их бесплатно. Как записывать и где лежат кассеты, объясняет Writing Tests.
ctxray test --layer L6-L7 --backend real --recordname: 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 проигрывают записанные ответы.
В каждом релизе есть шаблон ctxray.gitlab-ci.yml. Подключите его и унаследуйте скрытый job .ctxray:
include:
- remote: https://github.com/MairwunNx/ctxray/releases/latest/download/ctxray.gitlab-ci.yml
ctxray:
extends: .ctxraylatest следует за каждым релизом. Чтобы закрепить один, укажите его тег: 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: .ctxrayJob .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 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Везде работают два способа: 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 и шаблон:
- Кешируйте папку, которую печатает
ctxray cache dir, с ключом от хешаctxray.lock. - Сохраняйте
.ctxray/report/как артефакт, а.ctxray/report/junit.xmlотдайте в просмотр тестов вашего 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 installAction делает именно это, когда 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, ctxray запускает настоящий харнесс на копии проекта. В headless-режиме харнесс без спроса запускает MCP-серверы и хуки проекта, то есть выполняет код проекта. На macOS ctxray ограничивает запись прогона через sandbox-exec. В Linux и Windows такой песочницы нет: там песочница — контейнер CI или раннер, который выбрасывают после job.
Хостовые раннеры GitHub и GitLab одноразовые, так что с ними всё в порядке. На self-hosted раннере запускайте job в контейнере. ctxray doctor подскажет, какой случай у вашей машины: «На этой системе нет песочницы: запускайте L4 и выше в контейнере, как в CI».
Start
Use
Teams
Develop
По-русски
- Начало работы · Понятия · Loadout Stack · Режимы захвата
- Тесты · Конфигурация · Политики · Харнессы · Команды · Отчёты · Плагин Claude Code
- CI · Enterprise
- Архитектура · Локализация · Участие