concourse-ci

Concourse CI 流水线开发

针对编写、重构和优化 Concourse CI 流水线（v8.0+）的专家指导。

适用场景

• 创建或修改 Concourse 流水线
• 配置资源（git、registry-image、自定义类型）
• 使用 oci-build-task 构建容器镜像
• 排查资源检查失败或构建问题
• 从旧模式迁移（docker-image、重复作业）

快速参考

任务	现代方式（推荐）	旧方式（避免使用）
构建镜像	oci-build-task + registry-image	docker-image 资源
多环境部署	across 步骤修饰符	每个环境创建重复作业
动态流水线	set_pipeline + 实例化流水线	手动复制流水线
通知符号	UTF-8 字符（例如，勾号用 \u2714，叉号用 \u274c）	HTML 实体（例如，✓、✗）
资源样式	始终使用 icon: 属性	不设置图标

核心概念

流水线由资源（外部版本化工件）、作业（步骤序列）和可选的分组（用于组织 UI）组成。所有执行都在容器中运行。

关键步骤类型：get、put、task、set_pipeline、in_parallel、do、try、load_var。作业钩子：on_success、on_failure、on_error、on_abort、ensure。注意：on_failure（退出码非零）与 on_error（基础设施崩溃/OOM）不同——两者都要处理。使用 fly execute 在本地测试任务。

请参阅 references/core-concepts.md，了解步骤类型表、生命周期钩子和 fly CLI 要点。

关键注意事项

1. 强制推送后检测 Git 标签——转义正则表达式中的点，启用 clean_tags: true，分离读写资源，并使用 fly -t T check-resource -r pipeline/resource 强制重新检查。请参阅 references/resources-guide.md。
2. registry_mirror 格式不匹配——registry-image 需要对象（host: mirror），而 docker-image 需要 URL 字符串。在 CONCOURSE_BASE_RESOURCE_TYPE_DEFAULTS 中提供不同格式。请参阅 references/resources-guide.md。
3. GitLab Container Registry JWT 身份验证——JWT 端点位于 GitLab 主机上，而非注册表主机上。通过 Www-Authenticate 标头查找。请参阅 references/resources-guide.md。
4. git push --mirror 和默认分支——目标仓库的默认分支必须已存在于上游。如果不存在，pre-receive 钩子会因 "pre-receive hook declined" 而拒绝推送。请在首次镜像推送前设置默认分支。

参考资料

• references/pipeline-syntax.md -- 流水线、作业和资源的完整 YAML 架构
• references/core-concepts.md -- 步骤类型、生命周期钩子和 fly CLI 要点
• references/resources-guide.md -- Git-resource、registry-image、docker-image 迁移及注意事项
• references/best-practices.md -- 优化、故障排查、通知和部署模式
• references/resource-types-catalog.md -- 可用资源类型（Ansible、Terraform 等）

示例

examples/ 中的可用示例：

• basic-pipeline.yml -- 包含版本管理的构建-测试-部署
• modern-ci-cd.yml -- oci-build-task、across、build_log_retention
• multi-branch.yml -- 使用 set_pipeline 的动态分支流水线
• docker-build.yml -- 容器镜像构建与推送
• vars-template.yml -- 变量文件组织

验证

部署前使用 scripts/validate-pipeline.sh 检查流水线语法。