> ## Documentation Index
> Fetch the complete documentation index at: https://niceeval.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# 在 GitHub Actions 和 CI 中运行 NiceEval
> 把 NiceEval 接入 GitHub Actions 或任意 CI。评估用例失败时非零退出，输出 JUnit XML，并通过缓存加速重复运行。
评估用例应该和测试一样进入 CI。它们能在 PR 阶段发现 agent 行为回退，也能在 nightly job 中跟踪模型、成本和延迟变化。
## 退出码
默认情况下，只要存在失败的 gate，[NiceEval](https://niceeval.com/) 将以非零状态码退出。CI 中通常使用 `--strict`，让失败更明确。
```bash theme={null}
NICEEVAL_LANG=en npx niceeval exp ci \
--output ci \
--strict \
--json .niceeval/ci-summary.json \
--junit .niceeval/junit.xml
```
CI profile 不输出 ANSI、spinner 或动态表格。日志使用单一有序 stdout 流，只追加 start、低频 heartbeat、失败/错误、diagnostic 和最终 result；通过的 Attempt 不逐条打印。
## GitHub Actions 示例
```yaml theme={null}
name: evals
on:
pull_request:
workflow_dispatch:
jobs:
evals:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with:
node-version: 22
cache: npm
- run: npm ci
- run: >-
npx niceeval exp ci --output ci --strict
--json .niceeval/ci-summary.json
--junit .niceeval/junit.xml
env:
NICEEVAL_LANG: en
OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
```
## 配置 secrets
把 provider token 放进 GitHub Actions secrets。
只在运行评估用例的 step 暴露必要环境变量。
用最小评估用例或 `list` / dry run 先验证配置。
## JSON、JUnit 和结构化错误
```text theme={null}
niceeval: start total=24 configs=3 concurrency=10 reused=18
niceeval: errored locator=@12h8m4k1 eval=fixtures/button experiment=ci/codex phase=sandbox.create reason="E2B sandbox allocation failed after 5 attempts"
niceeval: result=failed passed=23 failed=0 errored=1 reused=18 duration=128s
niceeval: json=.niceeval/ci-summary.json
niceeval: junit=.niceeval/junit.xml
```
退出码是第一层红绿信号；JSON、JUnit 和结果快照是完整机器接口，日志行只用于搜索和 annotation。`errored` 行带 locator、eval/experiment 身份、已知时的正式 phase，以及一层 `reason` 摘要。详细 cause、stack 和 diagnostics 保存在 Attempt 的 `result.json`，可在保留 artifact 后运行 `niceeval show @` 回顾。
CLI 显式要求的 JSON/JUnit 和默认 results artifact 都是 required 输出：写入失败必须让 job 判红，不能只留 warning 后退出 0。把结果同时上报到 Braintrust 等实验平台的配置见 [Reporter 上报](./reporters)。
## 只检查发现
```bash theme={null}
npx niceeval list
```
适合快速验证评估用例文件能加载、配置没有明显错误。
## 缓存 `.niceeval/`
可以在 CI 中缓存 `.niceeval/`，但要确保 fingerprint 覆盖了影响结果的输入。对于 nightly 基准，通常保留完整 artifacts 更有价值。
## 控制并发
```bash theme={null}
npx niceeval exp ci --output ci --max-concurrency 2
```
标准 GitHub-hosted runner 上，Sandbox 评估用例并发不宜过高。远程 HTTP 评估用例可以按服务限流能力调高。
## 推荐模式
只跑关键评估用例和高风险路径，保持反馈快。
运行完整 experiment，记录 pass rate、成本和延迟趋势。
跑出来的结果要发布成静态报告站（Vercel / GitHub Pages 自动更新），见[通过 CI 发布报告](./publish-report)。