When to Use
Trigger on: automated deployment, continuous integration, pipeline setup, GitHub Actions, GitLab CI, build failing, deploy automatically, CI configuration, release automation.
Platform Selection
| Stack | Recommended | Why |
|---|
| Web (Next.js, Nuxt, static) | Vercel, Netlify | Zero-config, auto-deploys, preview URLs |
| Mobile (iOS/Android/Flutter) |
Codemagic, Bitrise + Fastlane | Pre-configured signing, app store upload |
| Backend/Docker | GitHub Actions, GitLab CI | Full control, self-hosted runners option |
| Monorepo | Nx/Turborepo + GHA | Affected detection, build caching |
Decision tree: If platform handles deploy automatically (Vercel, Netlify) → skip custom CI. Only add GitHub Actions when you need tests, custom builds, or deploy to your own infra.
Quick Start Templates
For copy-paste workflows, see templates.md.
Common Pipeline Pitfalls
| Mistake | Impact | Fix |
|---|
Using latest image tags | Builds break randomly | Pin versions: INLINECODE2 |
| Not caching dependencies |
+5-10 min per build | Cache
node_modules,
.next/cache |
| Secrets in workflow files | Leaked in logs/PRs | Use platform secrets, OIDC for cloud |
| Missing
timeout-minutes | Stuck jobs burn budget | Always set:
timeout-minutes: 15 |
| No
concurrency control | Redundant runs on rapid pushes | Group by branch/PR |
| Building on every push | Wasted resources | Build on push to main, test on PRs |
Mobile-Specific: Code Signing
The #1 pain point. iOS requires certificates + provisioning profiles. Android requires keystores.
The fix: Use Fastlane Match — stores certs/profiles in git repo, syncs across team and CI.
CODEBLOCK0
For detailed mobile CI/CD patterns (iOS, Android, Flutter), see mobile.md.
Web-Specific: Build Caching
Next.js/Nuxt builds are slow without cache. The No Cache Detected warning = full rebuild.
CODEBLOCK1
For framework-specific configs, see web.md.
Debugging Failed Builds
| Error Pattern | Likely Cause | Check |
|---|
| Works locally, fails in CI | Environment drift | Node version, env vars, OS |
| Intermittent failures |
Flaky tests, resource limits | Retry logic, increase timeout |
|
ENOENT / file not found | Build order, missing artifact | Check
needs: dependencies |
| Exit code 137 | Out of memory | Use larger runner or optimize |
| Certificate/signing errors | Expired or mismatched creds | Regenerate with Match/Fastlane |
What This Doesn't Cover
- - Container orchestration (Kubernetes) → see
k8s skill - Server configuration → see
server skill - Monitoring and observability → see
monitoring skill
使用时机
触发条件：自动部署、持续集成、流水线搭建、GitHub Actions、GitLab CI、构建失败、自动部署、CI配置、发布自动化。
平台选择
| 技术栈 | 推荐方案 | 原因 |
|---|
| Web（Next.js、Nuxt、静态站点） | Vercel、Netlify | 零配置、自动部署、预览URL |
| 移动端（iOS/Android/Flutter） |
Codemagic、Bitrise + Fastlane | 预配置签名、应用商店上传 |
| 后端/Docker | GitHub Actions、GitLab CI | 完全控制、支持自托管运行器 |
| 单体仓库 | Nx/Turborepo + GHA | 影响检测、构建缓存 |
决策树： 如果平台能自动处理部署（Vercel、Netlify）→ 跳过自定义CI。仅在需要测试、自定义构建或部署到自有基础设施时添加GitHub Actions。
快速启动模板
如需可直接复制的工作流，参见 templates.md。
常见流水线陷阱
| 错误 | 影响 | 修复方案 |
|---|
| 使用 latest 镜像标签 | 构建随机失败 | 固定版本：node:20.11.0 |
| 未缓存依赖 |
每次构建多花5-10分钟 | 缓存 node_modules、.next/cache |
| 工作流文件中包含密钥 | 在日志/PR中泄露 | 使用平台密钥、云服务OIDC |
| 缺少 timeout-minutes | 任务卡死消耗预算 | 始终设置：timeout-minutes: 15 |
| 无 concurrency 控制 | 快速推送时重复运行 | 按分支/PR分组 |
| 每次推送都构建 | 浪费资源 | 推送主分支时构建，PR时测试 |
移动端专项：代码签名
第一大痛点。iOS需要证书+配置文件。Android需要密钥库。
解决方案： 使用 Fastlane Match — 将证书/配置文件存储在git仓库中，在团队和CI间同步。
bash
一次性设置
fastlane match init
fastlane match appstore
在CI中
fastlane match appstore --readonly
详细的移动端CI/CD模式（iOS、Android、Flutter），参见 mobile.md。
Web端专项：构建缓存
没有缓存的Next.js/Nuxt构建非常慢。No Cache Detected 警告 = 完全重新构建。
yaml
GitHub Actions：持久化Next.js缓存
with:
path: .next/cache
key: nextjs-${{ hashFiles(
/package-lock.json) }}
框架特定配置，参见 web.md。
调试构建失败
| 错误模式 | 可能原因 | 检查项 |
|---|
| 本地正常，CI失败 | 环境差异 | Node版本、环境变量、操作系统 |
| 间歇性失败 |
不稳定测试、资源限制 | 重试逻辑、增加超时时间 |
| ENOENT / 文件未找到 | 构建顺序、缺少产物 | 检查 needs: 依赖 |
| 退出码137 | 内存不足 | 使用更大运行器或优化 |
| 证书/签名错误 | 凭证过期或不匹配 | 使用Match/Fastlane重新生成 |
未涵盖内容
- - 容器编排（Kubernetes）→ 参见 k8s 技能
- 服务器配置 → 参见 server 技能
- 监控与可观测性 → 参见 monitoring 技能
