如何将altimate-code接入CI/CD:Headless无头模式与JSON输出集成Git流水线的完整指南
如何将altimate-code接入CI/CD:Headless无头模式与JSON输出集成Git流水线的完整指南
altimate-code 是 Altimate 开源的数据工程 Agent 工具(支持 dbt、SQL 与 10 种云仓库),除了交互式 TUI,它还提供 Headless 无头模式:一条 altimate run 命令即可在 CI/CD 流水线中非交互式执行任意 prompt,输出纯文本或结构化 JSON,配合明确的退出码让 Git 流水线自动通过或失败。下文将手把手带你完成安装、环境变量配置、JSON 输出解析,并把它集成进 GitHub Actions 和 GitLab CI。
一、为什么 CI/CD 需要 Headless 无头模式
在 Git 流水线里跑 AI 助手,最关键的三个能力:
- 非交互式:不需要 TUI、不弹确认框,适合无头 Runner 环境
- 机器可读输出:
--output json输出结构化 JSON,方便流水线解析 - 明确的退出码:用退出码 0/1/2/3 驱动流水线成功或失败
官方文档入口:CI & Headless Mode
二、Headless 模式快速上手
一键安装
npm install -g altimate-code
运行第一条无头命令
altimate run "your prompt here"
核心参数一览:
| 参数 | 说明 |
|---|---|
--output json |
输出结构化 JSON 而非纯文本 |
--model <id> |
临时覆盖默认模型 |
--connection <name> |
指定仓库连接 |
--no-color |
关闭 ANSI 颜色(推荐 CI 日志使用) |
更多参数见 CLI Reference 或执行 altimate run --help。
无头模式的退出码
| 退出码 | 含义 |
|---|---|
0 |
任务成功完成 |
1 |
任务完成但发现可执行的问题(如反模式) |
2 |
配置错误(缺 API key、连接错误) |
3 |
工具执行错误(仓库不可达、查询失败) |
利用退出码让流水线对"发现问题"自动失败:
altimate run "validate models in models/staging/ for anti-patterns" || exit 1
三、通过环境变量完成 CI 配置(无需提交配置文件)
在 CI 中推荐用环境变量注入配置,而不是提交 altimate-code.json:
# LLM 提供商(二选一)
ALTIMATE_PROVIDER=anthropic
ALTIMATE_ANTHROPIC_API_KEY=your-key-here
# 或 OpenAI
ALTIMATE_PROVIDER=openai
ALTIMATE_OPENAI_API_KEY=your-key-here
# 仓库连接(以 Snowflake 为例)
SNOWFLAKE_ACCOUNT=myorg-myaccount
SNOWFLAKE_USER=ci_user
SNOWFLAKE_PASSWORD=***
SNOWFLAKE_DATABASE=analytics
SNOWFLAKE_SCHEMA=public
SNOWFLAKE_WAREHOUSE=compute_wh
💡 安全建议:CI 只读场景使用只读仓库账号,写权限凭证仅授予确实需要写文件的任务。详见 Security FAQ。
四、实战:3 个可直接抄的流水线模板
示例 1:每日成本巡检(GitHub Actions 定时任务)
# .github/workflows/cost-check.yml
name: Nightly Cost Check
on:
schedule:
- cron: '0 8 * * 1-5' # 工作日 8am UTC
jobs:
cost-check:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- name: Install altimate
run: npm install -g altimate-code
- name: Run cost report
env:
ALTIMATE_PROVIDER: anthropic
ALTIMATE_ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
SNOWFLAKE_ACCOUNT: ${{ secrets.SNOWFLAKE_ACCOUNT }}
SNOWFLAKE_USER: ${{ secrets.SNOWFLAKE_CI_USER }}
SNOWFLAKE_PASSWORD: ${{ secrets.SNOWFLAKE_CI_PASSWORD }}
SNOWFLAKE_DATABASE: analytics
SNOWFLAKE_WAREHOUSE: compute_wh
run: |
altimate run "/cost-report" --output json > cost-report.json
cat cost-report.json
- name: Upload cost report
uses: actions/upload-artifact@v4
with:
name: cost-report
path: cost-report.json
示例 2:部署后 SQL 反模式门禁
把这段加进 dbt 部署 workflow,在生产前拦截反模式:
- name: SQL anti-pattern check
env:
ALTIMATE_PROVIDER: anthropic
ALTIMATE_ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
run: |
altimate run "validate all SQL files in models/staging/ for anti-patterns and fail if any are found" \
--no-color \
--output json
示例 3:本地 pre-commit 自动生成测试
#!/bin/bash
# .git/hooks/pre-commit
STAGED_MODELS=$(git diff --cached --name-only --diff-filter=A | grep "models/.*\.sql")
if [ -n "$STAGED_MODELS" ]; then
echo "Generating tests for new models..."
altimate run "/generate-tests for: $STAGED_MODELS" --no-color
fi
五、无头模式下的 Trace 追踪
Headless 运行同样支持 Trace:每次 run 自动保存会话录制(含 LLM 调用、工具调用、token 与成本)。运行后即可查看:
altimate trace list
altimate trace view <session-id>
完整配置见 Trace 文档。
六、进阶:零 LLM 的确定性 SQL 检查(更快更省钱)
如果流水线里只是跑静态 SQL 检查,可以用 altimate check——完全不需要 LLM 和 API key,速度更快:
# 检查全部 SQL 文件(默认 lint + safety)
altimate-code check
# JSON 输出 + warning 即失败
altimate-code check --checks lint,safety --format json --fail-on warning
JSON 输出结构示例(便于流水线用 jq 解析):
{
"version": 1,
"files_checked": 3,
"checks_run": ["lint", "safety"],
"results": { "lint": { "warning_count": 1 } },
"summary": { "total_findings": 1, "errors": 0, "warnings": 1, "pass": true }
}
完整的 GitHub Actions / GitLab CI / pre-commit 集成模板都写在官方文档里:SQL Check (Headless)。
七、把 AI 评审挂到 Pull Request 上
GitHub Actions:自动 PR 评审机器人
# .github/workflows/altimate.yml
name: altimate
on:
pull_request:
types: [opened, synchronize]
jobs:
agent:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-node@v4
with: { node-version: "22" }
- name: Install altimate
run: npm install -g altimate-code
- name: Run agent
run: altimate github
env:
GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
⚠️ 注意:
GITHUB_TOKEN只用于仓库访问,不能用于 LLM 推理,必须单独提供 API key。详见 GitHub Actions 集成文档。
dbt 项目专用:dbt-pr-review
dbt 仓库推荐用 dbt-pr-review:它对每个 PR 输出签名的裁决(APPROVE / COMMENT / REQUEST_CHANGES),阻塞性发现全部由确定性引擎证明(列血缘、查询等价、PII 暴露),而 LLM 只做建议性评论、永不阻塞。支持 --json 输出完整裁决信封,--mode gate 可在 CI 中对 REQUEST_CHANGES 返回非零退出码。详见 dbt PR Review。
GitLab CI:合并请求评审
# .gitlab-ci.yml
altimate-review:
image: node:22
stage: review
script:
- npm install -g altimate-code
- altimate gitlab review "$CI_MERGE_REQUEST_PROJECT_URL/-/merge_requests/$CI_MERGE_REQUEST_IID"
variables:
GITLAB_PERSONAL_ACCESS_TOKEN: $GITLAB_TOKEN
ANTHROPIC_API_KEY: $ANTHROPIC_API_KEY
rules:
- if: $CI_PIPELINE_SOURCE == "merge_request_event"
详见 GitLab 集成文档。
八、常见问题速查
| 问题 | 解决 |
|---|---|
| CI 日志出现颜色乱码 | 加 --no-color |
| 想让检查失败时流水线变红 | 用退出码:`altimate run "..." |
| 如何拿到结构化结果 | --output json(run)或 --format json(check) |
| 想省钱/提速 | 静态检查用 altimate check(零 LLM),AI 分析才用 altimate run |
| 想看某次运行的详细记录 | altimate trace list / altimate trace view <session-id> |
| 需要 HTTP API 而非 CLI | altimate serve 启动 HTTP API 服务器,见 Server 文档 |
总结
把 altimate-code 接入 Git 流水线只需三步:
- 安装:
npm install -g altimate-code - 配置:用环境变量注入 LLM key 与仓库连接
- 运行:
altimate run "prompt" --output json --no-color,用退出码控制流水线门禁
静态场景用 altimate check,PR 评审场景用 altimate github / gitlab review,即可让 AI 成为你 CI/CD 中稳定的一环。🚀
延伸阅读:CLI 参考 · CI & Headless · SQL Check · dbt PR Review


